Home

Generated Java Method Format and Calling Parameters

1. Using the Compiler Option Argument Description cldc compact None 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 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 lt versionNumber gt 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 lt versionNumber gt is specified as x x for example compat 5 2 config lt filename gt 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 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
2. The characters method outputs the data with a type wrapper public void characters String svalue short typeCode indent String typeName new String AsnilType getTypeName typeCode typeName replace _ System out print lt typeName gt System out print svalue System out println lt typeName gt This illustrates the use of the typeCode argument for obtaining information on the ASN 1 type of the data Note that this is a simplified version of an XER formatting method A true implementation would need to do some massaging of the stringified data to fit the XER rules which in general do not follow the ASN 1 value formatting rules The implementation would also need some logic to check if the type wrapper should be output or not it is not always done in certain cases Finally note the constructor and finished method The constructor prints out the outer level wrapper tag Since Java does not have destructors a finished method is defined to terminate this tag This method must be called manually from within the application program after the Java decode method See the Reader java program to see how this is done Object registration is done as before in the PrintHandler example The only difference is that an object of the XMLHandler class is created instead of the PrintHandler class When compiled and executed the output from the Reader program looks like this lt Pers
3. H H HOH H m WZ ENTIFIER IE Fri data value OCTET STRING WITH COMPONENTS data value descriptor ABSENT The ASN 1 compiler is used to create a meta definition for this structure The definition is stored in the file AsnI EmbeddedPDV java or AsnlXerEmbeddedPDV java for XER An object created from the resulting Java class is populated just like any other compiler generated structure for working with ASN 1 data Parameterized Types The ASN1C compiler can parse parameterized type definitions and references as specified in the X 683 standard These types allow dummy parameters to be declared that will be replaced with actual parameters when the type is referenced This is similar to templates in C A simple and common example of the use of parameterized types is for the declaration of an upper bound on a sized type as follows SizedOctetString INTEGER ub OCTET STRING SIZE 1 ub In this definition ub would be replaced with an actual value when the type is referenced For example a sized octet string with an upper bound of 32 would be declared as follows OctetString32 SizedOctetString 32 The compiler would handle this in the same way as if the original type was declared to be an octet string of size 1 to 32 In the case of Java this would result in size constraint checks being added to the generated encode and decode methods for the type Another
4. new PrintStream new FileOutputStream message dmp We can also directly access the buffer as follows byte buffer encodeBuffer getBuffer int msglen encodeBuffer getMsgByteCnt catch Exception e System out println e getMessage e printStackTrace return The important thing to note is that not much changes from the normal procedure The only significant difference is that now the argument field can be directly populated with an instance of its target type Without table constraint checking logic this value would have to have been first encoded and then placed in an Asn OpenType container object Decoding Types with Table Constraints The general procedure to decode an ASN 1 message with table constraints is the same as without table constraints The only difference is that after decoding variable type fields will be replaced with instances of the actual types they are specified to contain in the associated object set instead of with generic Asn OpenType fields 97 Chapter 13 Generated Print Methods The print option causes print methods to be generated These functions can be used to print the contents of variables of generated types A print method is generated in each of the generated Java source files Generated Java Method Format and Calling Parameters The signature for a Java print method is as follows public void print PrintStream out String varName int level
5. udpInDatagrams OBJECT TYPE SYNTAX Counter32 MAX ACCESS read only STATUS current DESCRIPTION The total number of UDP datagrams delivered to UDP users udp 1 In this case a type definition is generated for the SYNTAX element and an Object Identifier value is generated for the entire item The name used for the type definition is lt name gt _SYNTAX where lt name gt would be replaced with the OBJECT TYPE name i e udpInDatagrams The name used for the Object Identifier value constant is the OBJECTTYPE name So for the above definitions the following two Java items would be generated 1 A udpInDatagrams_SYNTAX java file This would contain the udpInDatagrams_SYNTAX class definition and 2 AudpInDatagrams value definition in the UDP_MIB Values class 115 Chapter 21 Other Java based Platforms Java Micro Edition Support If your ASNIC license purchase includes support for BER or PER encoding it may also include support for Java Micro Edition You may find the following additional JAR files in your installation s java folder e asnIrt jme ber jar ASN1C Java ME runtime with support for BER e asnIrt jme per jar ASN1C Java ME runtime with support for PER When using ASNIC generated code on a Java Micro Edition platform observe the following e Use option cldc instead of java The generated code should be compatible with CLDC 1 1 e Do NOT use any of the following ASN1C compiler options print e
6. public lt name gt byte data super data public lt name gt byte data int offset int nbytes super data offset nbytes public lt name gt String value_ throws AsnlValueParseException super value_ This shows the class generated for a simple OCTET STRING assignment If a tagged or constrained type is specified specific encode and decode methods will be generated as well 30 ASN 1 Type to Java Class Mappings The constructors generated for this type provide additional options for populating the member variables in the base class In addition to passing the string directly using the data argument the string form can be used The string is passed in ASN 1 value notation format for either a binary string i e xxxx B hexadecimal string i e xxxx H or a character string 1 e xxxx A constructor also exists that allows a portion of a byte array starting at a given offset and consisting of a given number of bytes to be used to populate the variable Character String Types The Java version of the compiler contains support for the various ASN 1 character string types including the BMP Universal and UTF 8 string types All character strings in Java are based on 16 bit Unicode characters except for UniversalString which is based on a 32 bit character set All character string types are derived from the Asn CharString base class except the UniversalString This class contains the
7. Step 3 Close the output stream if opened try if out null out close catch Exception e If you compare this example with the BER encoding example in Figure 2 you will see the encoding procedure is almost identical This makes it very easy to switch encoding methods should the need arise All you need to do is change Asn1BerEncodeBuffer to Asn BerOutputStream and remove the explicit code that writes the messages into the stream Also closing of the stream should be added 59 Chapter 6 Generated BER DER CER Decode Methods For each ASN 1 production defined in the ASN 1 source file a Java decode method may be generated This method will decode an ASN 1 message into public member variables within the Java object As was the case for encode methods a decode method is only generated if it is required to alter the default method in the base class The Java model is built on inheritance from a set of common run time base classes These run time classes contain default implementations of encode decode methods that handle the encoding decoding of the basic types These default implementations include support for handling the universal tags associated with the types as defined in the X 680 standard Generated Java Method Format and Calling Parameters The signature for a Java BER decode method is as follows public void decode AsnlBerDecodeBuffer buffer boolean explicit int implicitLength throws Asnl
8. 37 ASN 1 Type to Java Class Mappings OPTIONAL keyword Elements within a sequence can be declared to be optional using the OPTIONAL keyword This indicates that the element is not required in the encoded message Optional elements are accounted for in the Java version of the compiler by simply using null object references to denote the absence of an element Remember that even the simplest primitive ASN 1 type definitions are wrapped in a Java class definition Therefore an object must be created for any type defined as an element within a SEQUENCE To populate a SEQUENCE object for encoding that contains optional elements the special constructor s for required elements only can be used The default constructor also can be used followed by the manual creation and setting of the individual element values The default constructor will initialize all element object references to null so only the items to be encoded need be populated DEFAULT keyword The DEFAULT keyword allows a default value to be specified for elements within the SEQUENCE ASNIC will parse this specification and treat it as it does an optional element Note that the value specification is only parsed in simple cases for primitive values It is up to the programmer to provide the value in complex cases For BER encoding a value must be specified be it the default or other value For DER or PER it is a requirement that no value be present in the encoding for the default
9. Frequently a SEQUENCE OF construct is used to define an array of some common type in an element in some other constructed type for example a SEQUENCE An example of this is as follows SomePDU SEQUENCE 40 ASN 1 Type to Java Class Mappings addresses SEQUENCE OF AliasAddress Normally this would result in the addresses element being pulled out and used to create a temporary type with a name equal to SomePDU addresses as follows SomePDU addresses SEQUENCE OF AliasAddress SomePDU SEQUENCE addresses SomePDU addresses However when the SEQUENCE OF element references a simple defined type as above with no additional tagging or constraint information an optimization is done to cut down on the size of the generated code This optimization is to generate a common name for the new temporary type that can be used for other similar references The form of this common name is as follows _SeqOf lt elementProdName gt So instead of this SomePDU addresses SEQUENCE OF AliasAddress The following equivalent type would be generated _SeqOfAliasAddress SEQUENCE OF AliasAddress The advantage is that the new type can now be easily reused if SEQUENCE OF AliasAddress is used in any other element declarations Note the illegal use of an underscore in the first position This is to ensure that no name collisions occur
10. useCachedLength false 82 Generated MDER Encode Methods if trace System out println Encoding was successful catch Exception e System out println e getMessage e printStackTrace finally try if encodeStream null encodeStream close catch Exception e Reuse of Java Encoding Objects The simple example above showed the procedure to encode a single record But what if you had to encode a series of the same type of record over and over again In such cases you can avoid some object creation and garbage collection by reusing objects you have already created The generated classes and the ASNIC runtime classes can often be viewed as reusable containers into which you can simply assign new data To show an example of object reuse suppose we were going to encode a series of octet strings The ASN 1 type for our data might be Data SEQUENCE first OCTET STRING second OCTET STRING third OCTET STRING The generated Java class would contain public member variables for each of the octet strings public AsnlOctetString first public AsnlOctetString second public AsnlOctetString third The most efficient way to repopulate these variables within a loop would be simply to assign the data to be encoded to the public value field of the Asn1OctetString objects You do not need to create new Asn1OctetString or Data objects each tim
11. UNIVERSAL 8 IMPLICIT SEQUENCE direct reference OBJECT IDENTIFIER OPTIONAL indirect reference INTEGER OPTIONAL data value descriptor ObjectDescriptor OPTIONAL encoding CHOICE single ASN1 type 0 ANY octet aligned 1 IMPLICIT OCTET STRING arbitrary 2 IMPLICIT BIT STRING The ASN 1 compiler is used to create a meta definition for this structure The definition is stored in the file Asn1lExternal java or Asn1XerExternal java for XER An object created from the resulting Java class is populated just like any other compiler generated structure for working with ASN 1 data EmbeddedPDV Type The ASN 1 EMBEDDED PDV type is a useful type used to include non ASN 1 or other data within an ASN 1 encoded message It was introduced in 1994 to replace EXTERNAL by removing unneeded fields and adding a few new ones to hold information that was missing This type is described using the following ASN 1 SEQUENCE 45 ASN 1 Type to Java Class Mappings EmbeddedPDV UNIVERSAL 11 IMPLICIT SEQUENCE identification CHOICE syntaxes SEQUENCE abstract OBJECT IDENTIFIER transfer OBJECT IDENTIFIER syntax OBJECT IDENTIFIER presentation context id INTEGER context negotiation SEQUENCE presentation context id transfer syntax OBJEC transfer syntax OBJECT IDEN fixed NULL ea a Eal
12. designating an element to be an open type by using the lt isOpenType gt configuration setting This setting causes the ASNIC compiler to insert an Asn OpenType placeholder in place of the type that would have normally been used for the element The data in its original encoded form will be stored in the open type container when the message is decoded The data within the open type container can be fully decoded later by using the normally generated decode function generated by the ASNIC compiler This stands in contrast to C and C code generation which requires a special decode function for this purpose In following example decoding of the element id is deferred Identifier SEQUENCE id INTEGER oid OBJECT IDENTIFIER The following configuration file is required to indicate the element id is to be processed as an open type i e that it will be decoded later lt asnilconfig gt lt module gt lt name gt modulename lt name gt lt production gt lt name gt Identifier lt name gt lt element gt lt name gt id lt name gt lt isOpenType gt 62 Generated BER DER CER Decode Methods lt element gt lt production gt lt module gt lt asnilconfig gt In the generated code the element id type will be replaced with an open type Asn OpenType and the type will be decoded as such When the top level decoding has finished the element may be decoded by taking the o
13. however the basic version will only generate code for the following types of value specifications BOOLEAN INTEGER ENUMERATED e Binary String 47 ASN 1 Type to Java Class Mappings e Hexadecimal String e Character String e OBJECT IDENTIFER The Pro version of the compiler will generate code for the following remaining types of value specifications e Enumerated e Real e Sequence e Set Sequence Of e Set Of e Choice If any of the above types of value specifications are detected in an ASN 1 module the compiler will generate a Java source file with a special class to hold the values The name of the source file and class is of the following format _ lt ModuleName gt Values In this definition lt ModuleName gt would be replaced with the name of the ASN 1 module in which the values are defined The following sections provide details on the Java constants generated for the various types of ASN 1 value specifications INTEGER Value Specification An INTEGER value specification causes a Java integer constant to be generated ASN 1 production lt name gt INTEGER lt value gt Generated Java constant public static final long lt name gt lt value gt BOOLEAN Value Specification A BOOLEAN value specification causes a Java boolean constant to be generated ASN 1 production lt name gt BOOLEAN lt value gt Generated Java constant public static final boolean
14. lt name gt lt value gt 48 ASN 1 Type to Java Class Mappings Binary String Value Specification This value specification causes two Java constants to be generated a numbits constant specifying the number of bits in the string and a data constant that hold the actual bit values ASN 1 production lt name gt BIT STRING bbbbbbb B Generated Java constants public static final int lt name gt _numbits lt numbits gt public static final byte lt name gt _data Oxhh Oxhh In the ASN 1 production definition the lowercase b s above represent binary digits 1 s or 0 s The generated code contains a numbits constant set to the number of bits binary digits in the string The data constant specifies the binary data using hexadecimal byte values Hexadecimal String Value Specification This value specification causes a Java constant to be generated containing a byte array of the hexadecimal byte values ASN 1 production lt name gt OCTET STRING hhhhhh H Generated Java constants public static final byte lt name gt Oxhh Oxhh In the ASN 1 production definition the lowercase h s above represent hexadecimal digits 0 9 a f or A F The generated constant specifies the binary data using hexadecimal byte values Character String Value Specification A character string declaration causes a Java String constant to be generated ASN 1 production lt name gt lt String
15. 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 lt sourceFile gt lt sourceFile gt 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 17 Using the Compiler Name Values Description versions of the compiler to accomplish this function lt pkgName gt 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 These attributes can be applied at the production level by including them within a lt production gt section Name Values Description lt name gt lt name gt module name This attribute identifies the module to which this section applies It is required lt isBigInteger gt n a This is a flag variable an empty element in XML terminology that specifies that this production will be used to sto
16. 2 Based on the information from step 1 the ROSE layer would know that the Open Type field contains a pointer and length to an encoded Login ARGUMENT component It would then route this information to the appropriate processor within the Application Layer for handling this type of message 3 The Application Layer would call the specific decoder associated with the Login ARGUMENT It would then have available to it the username password the user is logging in with It could then do whatever application specific processing is required with this information database lookup etc 4 Finally the Application Layer would begin the encoding process again in order to send back a Result or Error message to the Login Request A picture showing this is as follows Application Layer Call specific function to decode Login ARGUMENT and process data A Encoded message pointer and length Decode ROSE header message structure Invoke Open type structure contains message pointer and length of encoded Login ARGUMENT A Encoded ROSE message The login OPERATION also contains references to ERROR definitions These are defined using a separate MACRO that is built into the compiler The definition of this MACRO is as follows ROSE Layer ERROR MACRO BEGIN TYPE NOTATION Parameter VALUE NOTATION value VALUE INTEGER Parameter PARAMETER NamedType empty NamedType identifier type t
17. BER message involves the following three steps 1 Create a decode message buffer object to describe the message to be decoded 2 Invoke the decode method 3 Process the decoded data values The first step is the creation of a decode message buffer object The Asn BerDecodeBuffer object contains constructors that can either accept a message as a byte array or as an I O input stream The input stream option makes it possible 60 Generated BER DER CER Decode Methods to decode messages directly from other mediums other than a memory buffer for example a message can be decoded directly from a file The Asn BerDecodeBuffer object contains a method called peekTag that can be used to determine the outer level tag on a message This can be used to determine the type of message received in applications that must deal with multiple message types The generated decode method can then be invoked to decode the message The calling arguments were described earlier As per the Java standard this method must be invoked from within a try catch block to catch the possible exceptions that may be thrown Alternatively the method from which the decode method is called can declare that it throws the exceptions leaving them to be dealt with at a higher level The final step is to process the data All data is contained within public member variables so access is quite easy And of course Java has the distinct advantage of not requiring any clean up once
18. 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 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 11 Using the Compiler Common Code Generation Options Language Options Function Options Utity Options Sample Program Generation Generate writer
19. Parameterized TY Pes nyen aoeeoe sh sekesed Seeds neewtass EE EE E Ee EPE SERENE A See aos pe ENERE 46 Valle Specifications ei sia a a eevee de ebb teat dalbain dees ee E E dade ae a Noten de dabei 47 INTEGER Value SpecifiCan On snn Seb tase Soest head E Saeed ot NR Re R A sah eee NR we tawet seats 48 BOOLEAN Value Specification ss 0 ccc cece cece ence nec eee E A A EE E E eeaa sega EEA TENSE 48 Binary String Value Specification esseen epn E peA E EE EEAS sean eee EEE ESEE 49 Hexadecimal String Value Specification o ooeeeeseeeeeennseeeneeeesneressrerrsrrerrrresreressrerrerrerreerereee 49 Character String Value Specification m renien eeo a a E A a Eo aR ERE REEKS 49 Object Identifier Value Specification o ooosseneseseeeeseenseeeeereesreresrerrrrrsereresrrrrsrrerrereerreresre 49 ENUMERATED Value Specification eyen asr ee cee cence eecea ceca seca cena cea E E EE OEE ESS 50 REAL Value SPecipiC ahi On ro se seek eck pada oh ete dc dees eee Mook E hed sa uade beh E ste cee ANS 50 SEQUENCE Value Specification coe 3 coco satecs cock ted oE abs inden Sonus dade Soh asoe sy uRd ean Sad een ewe a see 50 SEL Value SpecifiCauon 22 cat Rii ett hae ase See te ee Soe Bae Sy ee a eee 31 SEQUENCE OF Vale Specification riyen e as ehese tsp een dss passed shed pugs cee yeee eee eek aes poets 51 SET OF Value Specificato aori e EE E E ERA REE EEE BOE OE pea 51 CHOICE Value Specification senine E dann E a E E dd boy ER E aN 51 5 Generated BER DE
20. Project OO i cpp gt sample_ber gt employee X 4 Search e Organize v New folder fl Se Fovodte S Name z Date modified Type WE Desktop employee acp 3 16 2010 11 19AM ACP File B Downloads I Recent Places a Libraries Ea Documents ad Music Pictures amp Videos m jE Computer fly COMPAQ C ta FACTORY_IMAGI aa 4 r File name employee acp X acproj acp z The project format has changed in ASNIC 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 Using the Compiler 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 Select Files and Directories ASN 1 XSD Files C acv630 cpp sample_ber employee employee asn Include Import Directories Configuration File s Browse Output Directory C acv630 cpp sample_ber employee Browse ea 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 highligh
21. The only primitive type that does not have a single member called value to represent its value is BIT STRING The Asn1BitString class also contains a second variable called numbits to specify the number of bits in the string Procedure for Calling MDER Encode Methods Once an object s member variables have been populated the object s encode method can be invoked to encode the value The general procedure to do this involves the following three steps 1 Create an encode output stream into which the value will be encoded 2 Invoke the encode method 3 Close the output stream The first step is the creation of an encode output stream an Asn MderOutputStream There is a single constructor which accepts a java io OutputStream As usual you may use a buffered output stream file output stream byte array output stream etc or some combination thereof The second step is the invocation of the encode method The calling arguments were described earlier Finally close the output stream A complete example showing how to invoke an encode method is as follows Note personnelRecord object was previously populated with data AsnlMderOutputStream encodeStream null try Step 1 Create an encode output stream ncodeStream new AsnlMderOutputStream new FileOutputStream filename Step 2 Invoke th ncode method Note that it must be done from within a try catch block personnelRecord encod encodeStream
22. The reason is because a version message could be received that does not contain the elements XSD lt xsd all gt Type Mapping As per the X 694 standard the XSD all type is mapped to an ASN 1 SEQUENCE type with a special element add named order This is added as a special element to the generated Java class with the name _order This contains an index entry for each element that identifies the order to elements are to be serilaized in when encoded in XML By default the array is initialized to encode the elements in the same order as specified in the type When an XML document of this type is decoded the order in which the elements are received in recorded in this array If the data is serialized out in binary form BER or PER the array is included in the encoding If is only transparent in XML encode decode operations to mimic the behavior of its handling in XSD An example of how this is used might be a gateway application that read XML data and then translated to binary form for transmission over a low bandwidth network When received on the other end the receiving application would 38 ASN 1 Type to Java Class Mappings transcode back from binary to XML Suppose the item being transmitted was described using an xsd all type that had three elements a b and c When the original XML document was received by the sending application suppose the elements were received in the order c b a The order array would record this fact and it
23. allows a value of any ASN 1 type to be specified On the encoding side a user can assign an object of any ASN 1 type to this variable and the encoding routine will call the appropriate encoder according to the table index value If the variable type is not present in the table and the Object Set is extensible than it can be encoded as an open type Otherwise an exception will be thrown On the decoding side the appropriate variable type is populated from the table based on the decoded index parameters The user can determine the variable type from the table index value If the variable type is not present in table then it will be decoded as an open type if the Object Set is extensible otherwise and exception will be thrown lt xsd any gt Handling The XSD any wildcard item is similar to an ASN 1 open type in semantics in that it allows any valid content to be present in that position in an XML document However an ASN 1 open type is not used to model an lt xsd any gt Instead a character string variable is used This stores the full XML text of the field in native XML form i e angle brackets and the like are not escaped Note that the XML text is not converted to different form when using binary encoding rules it is maintained as XML text External Type The ASN 1 EXTERNAL type is a useful type used to include non ASN 1 or other data within an ASN 1 encoded message The type is described using the following ASN 1 SEQUENCE EXTERNAL
24. an explicit tag should be applied to the encoded contents The average user will almost always want to set this argument to true The only time it would not be set to true is if a user wanted to just encode a contents field with no tag This argument is used primarily by the compiler when generating internal calls to properly handle implicit and explicit tagging Unlike the C C version a negative value is never returned form encode methods to indicate an encoding failure That is handled by the exception mechanism All ASNIC Java exceptions are derived from the Asn Exception base class See the section on exceptions for a complete list and description of the various exceptions that can be thrown If T O error occurs then the java io OException is thrown Procedure for Calling Java BER Stream Oriented Encode Methods Once an object s member variables have been populated the object s encode method can be invoked to encode the value The general procedure to do this involves the following three steps 1 Create an output stream object into which the value will be encoded 2 Invoke the encode method 3 Close the output stream The first step is the creation of an output stream object There are two forms of the constructor a constructor with one parameter OutputStream reference and one that allows specification of an internal buffer size A larger internal buffer size generally provides better performance at the expense of increased memory con
25. an index element value outside the object set then the user will have to encode the argument element as an Asn OpenType The following sample code populates the open type value Step 1 populate the Invoke type with data Invoke pdu new Invoke 96 Table Constraint Processing pdu opcode new AsnlObjectIdentifier new int 0 1 1 pdu argument new AsnlVisibleString objsys note opcode value is 0 1 1 so argument must be AsnlVisibleString type note the rest of the encode method will be same as general PER DER BER encoding rules Step 2 Create a message buffer object AsnlPerEncodeBuffer encodeBuffer new AsnlPerEncodeBuffer a Step 3 Invoke th ncode method Note that it must be done from within a try catch block try pdu encod encodeBuffer if trace System out println Encoding was successful System out println Hex dump of encoded record ncodeBuffer hexDump System out println Binary dump encodeBuffer binDump Invoke Step 3 Access th ncoded message component In this case we use methods in the class to write the component to a file and output a formatted dump to the message dmp file Write th ncoded record to a file encodeBuffer write new FileOutputStream filename Generate a dump file for comparisons ncodeBuffer hexDump
26. but you will get malformed XML if you try to encode a string having control characters as an attribute e XSD Generation The xsd switch does not currently generate XSD that can be used to validate EXTENDED XER encodings Actually in the worst cases it is not possible to produce XSD that validates precisely the set of valid EXTENDED XER encodings the closest approximations would either fail to reject some invalid encodings or fail to accept some valid encodings This is a result of the encoder s options which can produce mixed content models and XML Schema s limited abilities to constrain mixed content models Working with generated EXTENDED XER code As noted above when generating code for EXTENDED XER you will be working with the XML runtime as oppposed to the XER runtime This makes coding for EXTENDED XER slightly different from coding for XER e You will use Asn XmlEncoder instead of Asn XerEncoder e You will supply the name of the element when encoding a value Typically this will be the name of the ASN 1 PDU type Finally there is a sample reader and writer program in java sample_xer EmployeeEXER should you need to see an example Generated Encode Methods The generation of methods to encode data in XML is similar to how methods were generated in the BER DER and PER cases discussed previously For each ASN 1 production defined in the ASN 1 source file a Java encode method may be generated This fun
27. common example of parameterization is the substitution of a given type inside a common container type For example security specifications frequently contain a signed parameterized type that allows a digital signature to be applied to other types An example of this would be as follows SIGNED ToBeSigned SEQUENCE toBeSigned ToBeSigned algorithmOID OBJECT IDENTIFIER paramS Params signature BIT STRING An example of a reference to this definition would be as follows 46 ASN 1 Type to Java Class Mappings SignedName SIGNED Name where Name would be another type defined elsewhere within the module ASNIC performs the substitution to create the proper Java class definition for SignedName public class SignedName extends AsnlType public Name toBeSigned public AsnlObjectIdentifier algorithmOID public Params paramS public AsnlBitString signature When processing parameterized type definitions ASN1C will first look to see if the parameters are actually used in the final generated code If not they will simply be discarded and the parameterized type converted to a normal type reference For example when used with information objects parameterized types are frequently used to pass information object set definitions to impose table constraints on the final type Since table constraints do not affect the code that is generated by the compiler the parameterized
28. constants that can be used to set clear or test these named bits These symbolic constants are simply the bit names and values in the following general form public final static int lt name gt lt value gt The base class contains the following methods for using these generated constants 29 ASN 1 Type to Java Class Mappings e set This method can be used to set a bit in the bit string to be set There is also an overloaded version that takes a boolean value argument that can be used to set the bit to the given boolean value e clear This method can be used to clear the named bit in the bit string e isSet This method can be used to test if the named bit is set or clear See the Asn BitString class description in the run time section for more details on these methods OCTET STRING The ASN 1 OCTET STRING type is converted to a Java class that extends the Asn OctetString run time class This base class encapsulates the following public member variable public byte value The number of octets to be encoded or that were decoded is specified in the built in length component of the array object i e value length The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt OCTET STRING XSD Types lt xsd hexBinary gt lt xsd base64Binary gt Generated Java class public class lt name gt extends AsnlOctetString public lt name gt super
29. declaration for above ATTRIBUTE definition SupportedAttributes ATTRIBUTE name commonName 91 Table Constraint Processing This would result in the following Java constant being generated public static final ATTRIBUTE SupportedAttributes new ATTRIBUTE _TestValues name _TestValues commonName i Generated Information Object Table Structure Information Objects and Classes are used to define multi layer protocols in which holes are defined within ASN 1 types for passing message components to different layers for processing These items are also used to define the contents of various messages that are allowed in a particular exchange of messages The ASNIC compiler extracts the types involved in these message exchanges and generates encoders decoders for them The holes in the types are accounted for by adding open type holders to the generated structures These open type holders consist of a byte array for storing information on an encoded message fragment for processing at the next level The ASNIC compiler is capable of generating code in one of two forms for information in an object specification 1 Simple form in this form references to variable type fields within standard types are simply treated as open types and an open type placeholder is inserted 2 Table form in this form all of the classes objects and object sets within a specification result in the generation of code for parsing a
30. does not have a single member called value to represent its value is BIT STRING In this case the Asn BitString class contains a second variable called numbits to specify the number of bits in the string Procedure for Calling Java BER Encode Methods Once an object s member variables have been populated the object s encode method can be invoked to encode the value The general procedure to do this involves the following three steps 1 Create an encode message buffer object into which the value will be encoded 2 Invoke the encode method 3 Invoke encode message buffer methods to access the encoded message component The first step is the creation of an encode message buffer object Unlike the C C version of the product there is no choice to be made between a static or dynamic encode buffer In Java everything is dynamic There are two forms of 54 Generated BER DER CER Encode Methods the constructor a default constructor and one that allows specification of a message buffer size increment The size increment will determine how often the buffer will need to be resized to hold large messages If you know that you will be encoding large messages then this object should be constructed with a large value for the increment If you know that you will be encoding small messages in a constrained environment then this value can be set very low The default constructor sets the value to a reasonable mid range value see SIZE_ INCREMENT in
31. element If null is passed then the default element name for the referenced ASN 1 built in type is used For example lt BOOLEANS is the default element name for the ASN 1 BOOLEAN type The complete list of default element names can be found in the X 693 standard If an empty string is passed i e this tells the encode method to omit the element name string all together and just encode the value this is similar to implicit tagging in the BER case The XER or XML encode methods do not return a value This is different than the C C version that returns a negative status value to indicate an encoding failure For Java errors are reported via the exception mechanism All ASN1C Java exceptions are derived from the Asn Exception base class See the section on exceptions for a complete list and description of the various exceptions that can be thrown If I O error occurs then the java io OException is thrown Procedure for Calling Java XER Encode Methods The Java class variables corresponding to each of the ASN 1 types and method of population are the same as they were in the BER encoding case See the section Populating Generated Variables for Encoding for instructions on how to populate the variables prior to encoding Once an object s member variables have been populated the object s encode method can be invoked to encode the value The general procedure to do this involves the following three steps 74 Generated XML Methods
32. gt lt FieldName gt For a type field public AsniType lt FieldName gt For an information object field public lt ClassName gt lt FieldName gt For an information object set field public lt ClassName gt lt FieldName gt where lt FieldName gt is replaced with the name of the field 87 Table Constraint Processing lt TypeName gt is replaced with the generated runtime Java classname for the ASN 1 Type lt ClassName gt is replaced with the name of the information object class For a type field definition an element with type Asn Type is generated which is the base class for all types in the Java runtime package A type field can hold a value of any type Method and Constructor Generation Each generated Java class will have two constructors The first constructor will be the default constructor This will initialize each member variable value to null The second constructor will accept values for all the data members Example As an example consider the following ASN 1 class definition ATTRIBUTE CLASS amp Type amp id OBJECT IDENTIFIER UNIQUE WITH SYNTAX WITH SYNTAX amp Type ID amp id A file named ATTRIBUTE java is generated with following definition public class ATTRIBUTE public AsnilType Type public AsnlObjectIdentifier id public ATTRIBUTE Type null id null public ATTRIBUTE AsnlType Type_ AsnlObj
33. gt REAL lt value gt Generated Java constants public static final double lt name gt lt value gt SEQUENCE Value Specification A SEQUENCE value specification causes a final static instance of the Java class generated for the SEQUENCE to be generated ASN 1 production lt name gt lt SequenceType gt lt value gt Generated Java constants public static final lt SequenceType gt lt name gt new lt SequenceType gt new lt ElemlType gt lt elemlvalue gt new lt Elem2Type gt lt elem2value gt i For example consider the following declaration 50 ASN 1 Type to Java Class Mappings SeqType SEQUENCE oid OBJECT IDENTIFIER id INTEGER value SeqType oid 011 id 12 This would result in the following Java constant being generated for value public static final SeqType value new SeqType new AsnlObjectIdentifier new int 0 1 1 new AsniInteger 12 SET Value Specification The value code generation for the ASN 1 SET type is that same as that for SEQUENCE described above SEQUENCE OF Value Specification A SEQUENCE OF value specification causes a Java array constant to be generated ASN 1 production lt name gt lt SequenceOfType gt lt value gt Generated Java constants public static final lt SequenceOfType gt lt name gt new lt SequenceOfType gt
34. io import java util public class EmployeeNumber extends AsnilInteger public final static AsnlTag TAG new AsnlTag AsnlTag APPL AsniTag PRIM 2 public EmployeeNumber super 20 Generated Java Source Code Overview public EmployeeNumber int value_ super value_ pubilc void decode AsnlBerDecodeBuffer buffer boolean explicit int implicitLength throws AsnlException java io IOException final int llen explicit matchTag buffer TAG implicitLength super decode buffer false llen z if explicit amp amp llen Asn1lStatus INDI matchTag buffer AsnlTag EOC FLEN public int encode AsnilBerEncodeBuffer buffer boolean explicit throws AsnlException int aal super encod 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 tes
35. is generated to support the processing required to verify table constraints which is intended for use only in compiler generated code Therefore it is not necessary for the average user to understand the mappings in order to use the product The information presented here is informative only to provide a better understanding of how the compiler handles table constraints Information Object code will be generated in a Java source file with a special class to hold the values The name of the source file and class is of the following format _ lt ModuleName gt Values java In this definition lt ModuleName gt would be replaced with the name of the ASN 1 module in which the values are defined For each Information Object defined within a specification a Java constant is generated which is an instance of the ASN 1 CLASS definition for the object Each Information Object constant calls the Class constructor with the field value specified in the ASN 1 information object definition If the ASN 1 CLASS field is optional and the field value is absent in the Information Object definition then its corresponding member variable will be initialized to null If the ASN 1 CLASS field has a default value and its field value is absent in the Information Object then the generated code for the Information Object will set the Class field s value to the default value ASN 1 definition lt name gt lt ClassName gt lt InfoObject gt Generated Java cons
36. limit the message types that can be placed in this field The generated typedef for this field contains an open type Java Asn1 OpenType class reference to hold a previously encoded component to be specified in the final message Simple Form Code Generation In the simple form of information object code generation the Invoke type above would result in the following Java typedefs being generated public class Invoke extends AsnlType public AsnlInteger invokeID public OPERATION_operationCode opcode public AsnlOpenType argument The following would be the procedure to add the Invoke header type to an ASN 1 message body 1 Encode the body type 2 Get the message bytes and length of the encoded body 3 Plug the bytes into the data argument of the open type constructor in the Invoke type variable 4 Populate the remaining Invoke type fields 5 Encode the Invoke type to produce the final message In this case the amount of code generated to support the information object references is minimal The amount of coding required by a user to encode or decode the variable type field elements however can be rather large This is a trade off that exists between using the compiler generated table constraints solution as we will see below and using the simple form Table Form Code Generation If we now add table constraints to our original type definition it might look as follows Invoke SEQUENCE invokeID INTEGER opcode OP
37. lt NOT A NUMBER gt lt PLUS INFINITY gt and lt MINUS INFINITY gt are represented as NaN INF and INF respectively GeneralizedTime and UTCTime values are transformed into the XSD representation for dateTime YYYY MMDDTHH MM SS SSSS Zl I HH MM when encoded to XML When an XML document is decoded the time format is transformed into the ASN 1 format EXTENDED XER EXTENDED XER specified in X 693 allows you to vary the XML encoding of ASN 1 by using XER encoding instructions ASN1C supports EXTENDED XER in two different ways by compiling XSD and by compiling ASN 1 with XER encoding instructions Support for XER encoding instructions in ASN 1 is limited This section relates to our support for XER encoding instructions If some features you need are not supported you might consider using direct compilation of XSD How to Generate Code for EXTENDED XER If your ASN 1 contains XER encoding instructions ASN1C will automatically generate code for EXTENDED XER instead of BASIC XER This is true whether you use xer or xm1 on the command line If however any unsupported encoding instructions are found ASNIC will ignore all XER encoding instructions since it would not be capable of supporting EXTENDED XER for that specification Supported Instructions and Brief Summary ASNIC supports these instructions ATTRIBUTE and BASE64 Very brief summaries of the effects of these instructions follow e ATTRIBUTE This instruc
38. lt name gt String value_ super value_ SEQUENCE The ASN 1 SEQUENCE type is converted to a Java class that extends the Asn Type run time base class Public member variables are generated for each of the elements defined in the SEQUENCE Each of these member variables represents an object reference since all of the ASN 1 types are mapped to Java objects The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt SEQUENCE lt elementl name gt lt elementl type gt lt element2 name gt lt element2 type gt XSD Types lt xsd sequence gt lt xsd all gt Generated Java class public class lt name gt extends AsnlType public lt typel gt lt element1l name gt public lt type2 gt lt element2 name gt public lt name gt super public lt name gt lt typel gt lt argl gt lt type2 gt lt arg2 gt super lt elementli name gt lt argl gt 35 ASN 1 Type to Java Class Mappings lt element2 name gt lt arg2 gt public lt name gt lt basetypel gt lt argl gt lt basetype2 gt lt arg2 gt super lt elementl name gt new lt typel gt lt argl gt lt element2 name gt new lt type2 gt lt arg2 gt private void init public void decode public int encode public void print Note 1 The nota
39. much the same as with OSys XER and more ASNIC has two runtimes for XML The XER runtime This is used for basic and canonical XER e The XML runtime This is used for OSys XER and for EXTENDED XER whether compiling XSD or compiling ASN 1 with XER encoding instructions Because these two runtimes are so similar they are discussed in this chapter together As you read this chapter it is important to keep in mind when each of these runtimes is used so that you know which cases apply to you When it comes to decoding there is no difference the generated decoders use SAX Simple API for XML for parsing Note that you may use the xsd switch when generating XML encoders and decoders The XML schema produced from the ASN 1 specification using the xsd switch can be used to validate the XML messages generated using the XML encode functions Similarly an XML instance can be validated using the generated XML schema prior to decoding Compiler Invocation What is Generated xer flag is used to compile ASN 1 without XER encoding Generated code supports BASIC XER and canonical XER instructions xsd produces schema that validates BASIC XER encodings xer or xml flag is used to comple ASN 1 with supported Generated code supports EXTENDED XER only XER encoding instructions Gf any instructions are not supported all instructions are ignored and the above entry XSd produces schema that validates EXTENDED XER in th
40. new temporary types The names of the temporary types are of the form lt name gt _ lt element name1 gt _ lt element name2 gt _ lt element nameN gt Using this algorithm the ASN 1 type defined above would be reduced to the following equivalent ASN 1 types A xX SEQUENCE al INTEGER a2 BOOLEAN A SEQUENCE x A x y OCTET STRING SIZE The mapping of the ASN 1 types to J In the case of nesting levels greater For example consider the following X UE SEQ a SEQUENCI aa SEQUE bb INTEGE x In this case the generation of tempor 10 ava classes would then be done than two all of the intermediate element names are used to form the final name type definition that contains three nesting levels INT EG EAN ER y BOOL ary types results in the following equivalent type definitions X a aa SEQUENCE x INTEGER y BOOLEAN X a SEQUENCE aa X a aa bb INTEGER X SEQUENCE X a a Note that the name for the aa elemen This is a change from v5 1x and lowe aa The change was made to ensure t type is X a aa It contains both the name for a at level 1 and aa at level 2 r where only the production name and last element name would be used i e X uniqueness of the generated names when multiple nesting levels are used
41. otwes sob eietn Sesaeew ad sot el gees ob ieed tush REEI ETES 24 Inner ClaSSOSs cist eass E E seed tees vssetseosectsngosssosaai esos seasevissdaaddsaqsseeseac anes dea sewneesdde deaedeg sets 24 Error Handling tic ists espe een okt es E E eb ebsites Leb EEAS EEEE EEE E ee O ETES 25 4 ASN 1 Type to Java Class Mappings issiron i taian Soa ae E ess EE Poa D ee Ea meee 27 BOOLEAN at e tet etch Ssh E ae EEE E a Sian oe EREE AIR eA es 27 INTEGERS ys cssai fesc tase oases cd svaiitieas tops vgsedescuss shots sis yetisads versed ET 27 Large Inte ger Support eiin dssieeecs E E ent hi EEE Meal EIEEE EEEE EA ES VEE ig een oid 28 BEE STRING oiee cress ants a o bated is canta E A E E E E st between E ees 29 N med Bits vccs 25 sis gees a ok Coe eee B Vie oe Go OSes SEES SEUSS SIE A S e OREO a8 29 OCTET STRING o s225 55 ceed ussg sone fe raser eE dad sdisetas OEEO adosbowss oss Ssdauadeoeasuasedecasekonsudie EEESTIS 30 Character String TYPES e eero ies E a EEEE EE bec EEE beanie dees EEEE EEI EEA E EEE 31 ENUMERATED e e oaaae a atts oE E E E E cad EE E T E E R E R T EA eck 31 ALED D AE EE EEE E EA EE ES ABE E E EEE 33 OBJECT IDENTIFIER pe rhea neos ans soph EP NSE S ERRE REEVES EE EE PTEN ENERET SETAS 33 RELATIVE OID ssisiccccssig Becton eget s aE NKE E EE E loch eds E AE EEE SEE E E EEE ENS EE E iS 34 READ assis stories rat ee p a aaa EA E E E E E E E E E E ea 34 SEQUENCE mouiet civ Ris y R E bens a E E E EE E O gag S E e a E E E ra A aop a eE 35 Creation of
42. processing Then additional encode and decode methods are generated that use these tables to branch to the multiple message levels CLASS specification NOTE Class code generation is done only when tables is specified This additional code is generated to support the processing required to verify table constraints which is intended for use only in compiler generated code Therefore it is not necessary for the average user to understand the mappings in order to use the product The information presented here is informative only to provide a better understanding of how the compiler handles table constraints The Java class generated to model an ASN 1 class contains member variables for each of the fields within the class To create an instance of this class an information object is required to populate these variables with the values defined in the ASN 1 information object specification Java code will be generated for each ASN 1 CLASS definition in a separate Java source file containing a Java class corresponding to the ASN 1 CLASS definition The name of the source file and class is of the following format lt ClassName gt java In this definition lt ClassName gt would be replaced with the name of the ASN 1 CLASS for which this file is generated Data Member Generation For each of the following ASN 1 CLASS fields a corresponding member variable is generated in the Java class definition For a value field public lt TypeName
43. the X 208 specification or an open type from X 681 for example TYPEIDENTIFIER amp Type The last form of the constructor shown above is for an optimized form of Open Type encoding When encoding is done using BER an open type header can be directly added to the beginning of an encoded message component By using this form of the constructor you are indicating to the run time encoder that the encoded message component 44 ASN 1 Type to Java Class Mappings onto which a header is to be added is already present in the message buffer The advantage is that binary copies of the encoded message components are avoided both from the encode buffer to the open type object and from the open type object back to the encode buffer For XER a new class derived from the Asn OpenType class was created This is the Asn XerOpenType class and this must be used whenever an open type is required for XER The reason for creating a special derived class is because of dependencies on XML parser classes defined within this class If these were added directly to the Asn OpenType class a user would need to always have XML parser jar files included in their classpath even if working with BER DER or PER only If the tables command line option is selected and the ASN 1 type definition references a table constraint the code generated is different In this case Asn OpenType above is replaced with Asn1Type This the base class for all ASN 1 types This
44. the base class contains two protected member variables choiceID and element that must be set consistently This is the only instance of a mapped type where the mapped element values do not have public access The following demonstrates setting a variable of the TestChoice structure defined above to use the first option TestChoice testChoice new TestChoice testChoice set_a new AsnlInteger 222 Accessing the Choice Element Value after Decoding To access the element in a choice construct after decoding the following two methods can be used both are defined in the Asn1 Choice base class 1 getChoicelD this returns an identifier equal to one the generated choice identifier constants and 2 getElement this returns a reference to the decoded element object It is of type Asn1Type but it can be upcast to the correct element type using information from the getChoiceID call In addition the compiler generates a getElemName method that can be used to get the textual name of the decoded element XSD lt xsd union gt Type Mapping The lt xsd union gt type is handled in a similar fashion to a choice type The main difference is that the items in a union are not tagged As per X 694 special element names are generated for these items for use in an ASN 1 CHOICE type 43 ASN 1 Type to Java Class Mappings These names are based on the base name alt and progress with sequential digits added for each addional union it
45. the stream try if out null out close catch Exception e If you compare these examples with the other encoding examples you will see the procedures are similar This makes it very easy to switch encoding methods should the need arise 77 Generated XML Methods In the case of XML encode the procedure is very similar The only difference is that it is not necessary to call the encodeStartDocument and encodeEndDocument methods The are built into the generated encode method for PDU data types The resulting XML document from running the program above is as follows lt xml version 1 0 encoding UTF 8 gt lt PersonnelRecord gt lt name gt lt givenName gt John lt givenName gt lt initial gt P lt initial gt lt familyName gt Smith lt familyName gt lt name gt lt number gt 51 lt number gt lt title gt Director lt title gt lt dateOfHire gt 19710917 lt dateOfHire gt lt nameOfSpouse gt lt givenName gt Mary lt givenName gt lt initial gt T lt initial gt lt familyName gt Smith lt familyName gt lt nameOfSpouse gt lt children gt lt Childinformation gt lt name gt lt givenName gt Ralph lt givenName gt lt initial gt T lt initial gt lt familyName gt Smith lt familyName gt lt name gt lt dateOfBirth gt 19571111 lt dateOfBirth gt lt ChildInformation gt lt Childinformation gt lt name gt lt givenName gt Susan lt givenName gt lt initial gt B lt init
46. type definition is reduced to a normal type definition and references to it are handled in the same way as defined type references This can lead to a significant reduction in generated code in cases where a parameterized type is referenced over and over again For example consider the following often repeated pattern from the UMTS 3GPP specs ProtocolIE Field RANAP PROTOCOL IES IEsSetParam SEQUENCE id RANAP PROTOCOL IES amp id IEsSetParam criticality RANAP PROTOCOL IES amp criticality IEsSetParam id value RANAP PROTOCOL IES amp Value IEsSetParam id In this case JEsSetParam refers to an information object set specification that constrains the values that are passed for any given instance of a type referencing a ProtocollE Field The compiler does not add any extra code to check for these values so the parameter can be discarded After processing the Information Object Class references within the construct refer to the Information Objects section for information on how this is done the reduced definition for ProtocollE Field becomes the following ProtocollIE Field SEQUENCE id ProtocolIE ID criticality Criticality value ASN 1 OPEN TYPE References to the field are simply replaced with a reference to the generated ProtocollD Field class Value Specifications The ASNIC compiler can parse any type of ASN 1 value specification
47. would be included in the binary serialization When the receiver decoded the message on the other end the order information would be available along with the element data The receiver could then reconstruct the XML document with the items in the same order as received SET The ASN 1 SET type is converted into a Java class that is identical to that for SEQUENCE as described in the previous section The only difference between SEQUENCE and SET is that elements may be transmitted in any order ina SET whereas they must be in the defined order in a SEQUENCE The only impact this has on ASNIC is in the generated decoder for a SET type The decoder must take into account the possibility of out of order elements This is handled by using a loop to parse each element in the message Each time an item is parsed an internal mask bit within the decoder is set to indicate the element was received The complete set of received elements is then checked after the loop is completed to verify all required elements were received SEQUENCE OF The ASN 1 SEQUENCE OF type is converted to a Java class that extends the Asn Type run time base class An array public member variable named elements is generated to hold the elements of the defined type The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt SEQUENCE OF lt type gt XSD Types Elements or content group definitions containing t
48. you are done with the data The garbage collector will collect the unused memory when it is no longer referenced A complete example showing how to invoke a decode method is as follows try Step 1 create a decode message buffer object to describe the message to be decoded This example will use a file input stream to decode a message directly from a binary file Create an input file stream object FileInputStream in new FileInputStream filename Create a decode buffer object AsnliBerDecodeBuffer decodeBuffer new AsnlBerDecodeBuffer in Step 2 create an object of the generated type and invoke the decode method PersonnelRecord personnelRecord new PersonnelRecord personnelRecord decode decodeBuffer Step 3 process the data if trace System out println Decode was successful personnelRecord print System out personnelRecord 0 catch Exception e System out println e getMessage e printStackTrace return Reuse of Java Decoding Objects The sample above showed the BER decoding of a single message In a typical application a loop would be involved to decode a series of messages While it would be possible to use the code shown above in a loop it would not be 61 Generated BER DER CER Decode Methods the most efficient way to decode the messages Objects should be reused where possible to avoid the overhead of
49. 1 Create an encode message buffer or output stream object into which the value will be encoded 2 Invoke encode methods These include the encodeStartDocument and encodeEndDocument methods from the Asn1XerEncodeBuffer class and the encode method from the ASNIC generated class 3 If the encode message buffer is used invoke encode message buffer methods to access the encoded message component If the output stream is used close the stream The first step is the creation of an encode message buffer object For XER encoding this is an object of the Asn1XerEncodeBuffer class The following constructors are available for creating an XER encode buffer object public AsnlXerEncodeBuffer public AsnlXerEncodeBuffer boolean canonical int sizeIncrement The default constructor sets all internal buffer control variables to default values Canonical XER is set to false and size increment is set to 1024 The other forms of the constructor allow these variables to be changed Canonical XER specifies that the canonical form of XER encoding CXER as specified in X 693 should be used Size increment specifies the amount by which the dynamic encode buffer should be expanded when it fills up This should be set lower for small memory constrained environments and higher if large messages are being encoded If the output stream method is used then the first step is the creation of an output stream For XER encoding this is an object of the Asn XerOutp
50. ASN 1 source file It is possible to have an ASN 1 source file containing multiple module definitions in which modules IMPORT definitions from other modules An example of this would be the following ModuleA DEFINITIONS BEGIN IMPORTS B From ModuleB Ae s B END ModuleB DEFINITIONS BEGIN B INTEGER END This entire fragment of code would be present in a single ASN 1 source file 110 Chapter 19 Compact Code Generation The compact command line switch can be used to reduce the amount of source code generated for a given ASN 1 specification This is done by generating the code for simple definitions inline within structured type definitions instead of creating separate classes For example consider the following definition X APPLICATION 1 INTEGER Y APPLICATION 2 OCTET STRING SIZE 1 32 Z APPLICATION 3 SEQUENCE x 0 X y 1 Y In normal mode the compiler would generate three classes for these productions one corresponding to X Y and Z respectively But in compact mode it is recognized that a user would normally not be interested in encoding or decoding X and Y on their own They would primarily be interested in encoding or decoding the more complex structured types i e the PDU s that make up fully formed messages Taking this into account when compact is specified the compiler will not generate separate classes for X and Y
51. Asn 1EncodeBuffer java as of this writing the value was set to 1024 The second step is the invocation of the encode method The calling arguments were described earlier As per the Java standard this method must be invoked from within a try catch block to catch the possible Asn Exception that may be thrown Alternatively the method from which the encode method is called can declare that it throws an Asn1 Exception leaving it to be dealt with at a higher level Finally encode buffer methods can be called to access the encoded message component The encode method itself returns the length of the component so this item is already known however there is a getMsgLength method available if you want to access this length from a different location Unlike C or C a pointer to where the message starts in the encode buffer cannot be returned recall that BER encoding is done from back to front so a message rarely starts at the beginning of a buffer However the Java API provides an object called a ByteArrayInputStream that provides a way to look at the encoded component as a stream The encode buffer object therefore provides a method called getByteArrayInputStream which is the preferred way to access the encoded component In addition to getByteArrayInputStream there is a getMsgCopy function that will retrieve a copy of the generated message into a byte array object This is somewhat slower because a copy needs to be done The encode buffer class a
52. ERATION amp operationCode My ops argument OPERATION amp ArgumentType My ops opcode 93 Table Constraint Processing The My ops constraint on the opcode element specifies an information object set not shown that constrains the element value to one of the values in the object set The My ops opcode constraint on the argument element goes a step further it ties the type of the field to the type specified in the row that matches the given opcode value ASNIC generates an in memory table for each of the items in the information object sets defined in a specification In the example above a table would be generated for the My ops information object set The code generated for the type would then use this table to verify that the given items in a structure that reference this table match the constraints The Java type generated for the SEQUENCE above when tables is specified would be as follows public class Invoke extends AsnlType public AsnlInteger invokeID public OPERATION_operationCode opcode public AsniType argument This is almost identical to the type generated in the simple case The difference is that ASN Type is used instead for the argument element instead of ASN1 OpenType This type is defined as the base class for all the generated ASN 1 types It holds the value to be encoded or decoded The way a user Would use this to encode a value of this type is as follows 1 Popula
53. Exception java io Exception The buffer argument is a reference of an Asn BerDecodeBuffer object that describes the message that is being decoded This must be created and initialized before calling any decode method See the description of this class in the Java Run Time Classes section for details on how this class is used The explicit and implicitLength arguments specify whether or not an explicit tag should be parsed from the encoded contents The average user will almost always want to set explicit to true and implicitLength to zero The only time these arguments would not be set this way is if a user wanted to directly decode contents with no tag length information These arguments are used primarily by the compiler when generating internal calls to properly handle implicit and explicit tagging The decode method returns no result Unlike the C C version a negative status value is not returned to indicate a failure That is handled by the exception mechanism All ASN1C Java exceptions are derived from the Asn1 Exception base class See the section on exceptions for a complete list and description of the various ASN 1 exceptions that can be thrown The java io Exception that can be thrown is in the read method within the decode buffer base class This method attempts to read data from an input stream using the methods in the java io package Procedure for Calling Java BER Decode Methods The general procedure to decode an ASN 1
54. GER type is converted to a Java class that extends the AsnJInteger run time class This base class encapsulates the following public member variable public long value 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 27 ASN 1 Type to Java Class Mappings The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt INTEGER XSD Types lt xsd integer gt lt xsd byte gt lt xsd short gt lt xsd int gt lt xsd long gt lt xsd unsignedByte gt lt xsd unsignedShort gt lt xsd unsignedInt gt lt xsd unsignedLong gt lt xsd positivelInt gt lt xsd nonPositivelInt gt lt xsd negativelInt gt lt xsd nonNegativelInt gt Generated Java class public class lt name gt extends AsnlInteger public lt name gt super public lt name gt 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
55. R CER Encode Methods sseesueeessuerrsrerrrrrsrreresrerrsrrerrsresrrrresrerrerrerrerrerrreeset 53 Memory buffer Based Definite Length Encoders s sesisssiresirssrresrsrrrssrresreerresrrrerterrterrreereeeereeee 53 Generated Java Method Format and Calling Parameter cccccceeceeecneeceeece seen eeea een eeneeens 53 Populating Generated Variables for Encoding ccccceec cece ence nnce nce n nce enceneceeeceeeseeesaeseaeeeges 54 Procedure for Calling Java BER Encode Methods 1 cceccceceeeceeece ence nese eeceeeeaesea essa eeaa scans 54 Reuse Of Tava En c dinge Objects oree nene ee a E E EEE EE EAEE E 56 Stream Oriented Indefinite Length Encode Methods seesneseesesesseerrsreserrresreresrrerrsrreerrresrereereeees 57 Generated Java Method Format and Calling Parameters ccccceeceeece eee eeceeeea teen tenn eeueeens 37 Procedure for Calling Java BER Stream Oriented Encode Methods n 58 6 Generated BER DER CER Decode Methods 0 cece cece cece cnce cece ne ceneceneeeeeeeeeeeeaeseaeseaeeeaeeae sean eegs 60 Generated Java Method Format and Calling Parameters 0 cc ccec cece eeece ence ence eeceeeeeeeen seen eens eeun eens 60 Procedure for Calling Java BER Decode Methods 2 0 0 0 cece cece cece ccee cence eece seca cece sean eeae eens eeneeeeeeeees 60 Reuse of Java Decoding Objects 2 0 00 cece cece cece cence EE a EE aA E E EE EE EEA eN 61 Deferred Decoding see
56. SN1C 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 allow ambig tags This option suppresses the check that is done for ambiguous tags within a SEQUENCE or SET type within a specification Special code is generated for the decoder that assigns values to ambiguous elements within a SET in much the same way as would be done if the elements were declared to be in a SEQUENCE asnstd x680 This option instructs the compiler x208 to parse ASN 1 syntax conforming mixed to the specified standard x680 the default refers to modern ASN 1 as specified in the ITU T X 680 X 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 cer None This option instructs the compiler to generate functions that implement the Canonical Encoding Rules CER as specified in the ASN 1 standards
57. Temporary Types crre icecsssess ssovis eases ses vee oeseddesSases sseusosheessneas seeder EROT saugsseems ese eees 37 OPTIONAL Keyword 285 si0cencas ios er E EEE EE EEE EEES REA EEEE RETETE 38 DEFAULT Keyword zs ern eiaa E a sath yes 0S E E E EE EAE E E S 38 Extension Elements ois is Boots BERENS Moc Oe E EEA EES RE a E E E TeS 38 XSD lt xsd ll gt Type Mapping ic cs coves cusessissetta ed E raon rE rA SEREDE OSPINA ESEO TEINE PRUNON REPE IKOONE R 38 SEE EEE E EE EE A E E A E EEEE 39 SEQUENCE OB Caia er a E E A E a gata ea T E a S E E AE A E 39 Generation of Temporary Types for SEQUENCE OF Elements o oo 40 SEQUENCE OF Type Elements in Other Constructed Types sooocsseecsseeeeseeeeseeserrsreerrsrrereeees 40 SEP OF pie oae E EEE E E EEE E E EET E EENS 41 CHOIGE ja a E a e E EO E E E E E E 41 Creation of Temporary Types k ssrin coiii ence ence ATE EE EESE EKS EIEEE oe Es 43 Populating Generated Choice Structures for Encoding 1 2 0 1 cccccsecc nsec necc ence ence eeceeeceeesaeeeaeeenes 43 lil ASNIC Accessing the Choice Element Value after Decoding 1 c1ccceccseceneccneceneec ence ence eeceeesaeeeaeeeaes 43 Open Ty per case engin ceedecse Seg ae UU Ae ac sesh Oe A Rosen ed hue ated E 44 External Typen snena ge egaee ies e eee saUl ies hse ceae aes hea ddey bets coat d gest nod nes Sheed S E loute meee ueceo sary 45 EmbeddedPDV T pek m Sadie ects ies decent el seeks arash eta yeer teeta dis dete a eet eee 45
58. The out argument specifies a PrintStream object to which the output should be written The Java class System out should be specified to write to standard output The varName argument is used to specify the top level variable name of the item being printed Normally this would be set to the same name as the variable declared in your program that holds the object being printed For example if you declared a variable called personnelRecord to hold a PersonnelRecord object the varName object would be set to personnelRecord The level argument is used to specify the indentation level for printing nested types The user would always want to set this to zero at the outer level For example the call to print the personnelRecord from the previous examples would be as follows personnelRecord print System out personnelRecord 0 The output would be formatted as follows personnelRecord name givenName John initial P familyName Smith number 51 title Director dateOfHire 19710917 nameOfSpouse givenName Mary initial T familyName Smith children 0 name givenName Ralph initial T familyName Smith dateOfBirth 19571111 children 1 98 Generated Print Methods name givenName Susan initial B familyName Jones dateOfBirth 19590717 99 Chapter 14 Generated Compare Methods The compare command line option causes an equals m
59. This additional code is generated to support the processing required to verify table constraints which is intended for use only in compiler generated code Therefore it is not necessary for the average user to understand the mappings in order to use the product The information presented here is informative only to provide a better understanding of how the compiler handles table constraints Information Object code will be generated in a Java source file with a special class to hold the values The name of the source file and class is of the following format _ lt ModuleName gt Values java In this definition lt ModuleName gt would be replaced with the name of the ASN 1 module in which the Information Object Sets are defined Each Information Object Set specification causes a Java constant to be generated containing an array of Information Object values Each object in the array is an instance of the equivalent Java class representing the corresponding ASN information object As of this writing a static array is used to hold the objects but this could be changed to something like a linked list or hash ASN 1 definition lt name gt lt ClassName gt lt Information Object1l gt lt Information Object2 gt Generated Java constants public static final lt ClassName gt lt name gt new lt ClassName gt lt Information Object1 gt lt Information Objectl1 gt For example consider the following Information Object Set
60. Type gt ccccccc Generated Java constants public static final String lt name gt ccccccc In the ASN 1 production definition lt StringType gt would be replaced with one of the ASN 1 character string types for example A5String The lowercase c s represent string characters The generated constant is simply the string in Java form Object Identifier Value Specification An object identifier value specification causes a Java integer array to be generated containing the subidentifier values ASN 1 production 49 ASN 1 Type to Java Class Mappings lt name gt OBJECT IDENTIFIER lt oidvalue gt Generated Java constants public static final int lt name gt idl id2 idn For example consider the following declaration oid OBJECT IDENTIFIER ccitt b 5 10 This would result in the following Java constant being generated public static final int oid 0 5 10 ENUMERATED Value Specification An ENUMERATED value specification causes a Java integer constant to be generated ASN 1 production lt name gt lt enumtype gt lt enumitem gt Generated Java constants public static final int lt name gt lt enumvalue gt enumvalue will be the sequential integer value corresponding to the enumitem in enumtype REAL Value Specification A REAL value specification causes a Java double constant to be generated ASN 1 production lt name
61. aN E 100 15 Generated Sample Programs osson e aE teases of Ruben a E E O OEA ade del e ER 101 16 Generated Buld Script eaen ea a a a E E E E E ENEE 102 17 Event Handler Interface p en e a niece E AS E N E ghee ee 103 How It Works eseria ee ae E E E Ee E E AEA TE ER EE AE EOI SES EENE 103 How to Use Itaco en a E as E E E a E E E E S 104 Example 1 A Formatted Print Handler zistos rinn ee enio eee E 104 Example 2 An XML Converter Classen ra ree a EE cece cece EE TEE E EEE SEE 106 18 IMPORT EXPORT OB TYDES sce ena eea ep NE r E venous EEA gest ER ERARE A ESE ETNE S 110 19 Gompact Code Generaton i isscasnei e ete Ree a a e aa E E Se N ee eG a EEN 111 20 ROSE and SNMP Macro SUppO T errereen e a a a E E E AE a Guegeerteseeds 112 ROSE OPERATION and JBRROR i520 23 circ e E E E eee cts eee aes AS 112 SNMP OBJEC THAT YPE css dese ccaucen teenager e tee eco hee vedapnswads seh ese dhsba sua osentee cebeh eenageabera nba vont 115 2 Other Java based Platlorms cssciisseti E r E EE ee des Hee eel pot ened na E E AE Pea 116 Java Micro Edition SUPPOLE sere saves Geet gas cae ea A hve e dee sycbsaoueeysdedaeeaes oe a E Ea A E ES 116 ANATOLA eeen a E EE E a cxsaubvnwe cba cireg sa eRe enbbatee E Reng Ce RS 116 Chapter 1 Overview of ASN1C for Java The ASNIC 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 enc
62. alues out of OPERATION definitions An example of an OPERATION definition is as follows login OPERATION 112 ROSE and SNMP Macro Support RGUMENT SEQUENCE username IA5String password IA5String ESULT SEQUENCE ticket OCTET STRING welcomeMessage IA5String RRORS authenticationFailure insufficientResources 1 mob In this case there are two embedded types an ARGUMENT type and a RESULT type and an integer value 1 that identifies the OPERATION There are also error definitions The ASNIC compiler generates two types of items for the OPERATION 1 It extracts the type definitions from within the OPERATION definitions and generates equivalent Java classes and encoders decoders and N It generates value constants for the value associated with the OPERATION i e the value to the right of the in the definition The compiler does not generate any structures or code related to the OPERATION itself for example code to encode the body and header in a single step The reason is because of the multi layered nature of the protocol It is assumed that the user of such a protocol would be most interested in doing the processing in multiple stages hence no single function or structure is generated Therefore to encode the login example the user would do the following j At the application layer the Login ARGUMENT structure would be populated with th
63. andler implements AsniNamedEventHandler protected String mVarName protected int mIndentSpaces 0 public XMLHandler String varName mVarName varName System out println lt mVarName gt mIndentSpaces 3 public void startElement String name int index indent System out println lt name gt mIndentSpaces 3 public void endElement String name int index mindentSpaces 3 indent System out println lt name gt public void characters String svalue short typeCode indent String typeName new String AsnilType getTypeName typeCode typeName replace _ System out print lt typeName gt System out print svalue System out println lt typeName gt public void finished System out println lt mVarName gt private void indent for int i 0 i lt mIndentSpaces i System out print This is very similar to the PrintHandler class defined earlier The startElement method simply opens an XML element block public void startElement String name int index indent System out println lt name gt mIindentSpaces 3 107 Event Handler Interface The endElement method closes it public void endElement String name int index mindentSpaces 3 indent System out println lt name gt
64. arate methods are defined for all of the different data types This implementation is more closely aligned with the standard SAX implementation for XML The reason it is done this way in Java and not C is because it is much easier to stringify values Since memory management is built in to Java it is easy to create a string and pass it out This is a problem in C because it becomes a performance issue if too many malloc s are done and it also places a burden on the user to free the memory for the allocated strings The signature for the characters method is as follows void characters String svalue short typeCode The svalue argument contains the stringified value The format of this value is ASN 1 value notation for the value as defined in the X 680 standard The typeCode argument contains an identifier that specifies the ASN 1 type of the value The identifier corresponds to the universal identifier values the ID number in the universal tags for each of the primitive data types The only exception to this rule is that the identifier 99 was added to represent an Open Type construct Constants for all of the identifier values are provided in the Asn Type class See the javadoc documentation for this class for a list of the constants How to Use It To define event handlers two things must be done 1 One or more new classes must implement the Asn NamedEventHandler interface 2 Objects of these classes must be created and registered prio
65. as published in the ITU T X 693 standard e 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 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 Chapter 2 Using the Compiler Running ASN1C The ASNIC compiler distribution contains command line compiler executables as well as a graphical user interface GUD wizard that can aid in the specification of compiler options Please refer to the ASNIC 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 A
66. bles legacy setting in C C Do not generate inline containing types noContaining Space Optimization Generate compact code compact E Do not generate indefinite length processing code noIndefLen E Do not generate code to save restore unknown extensions noOpenExt E Do not generate types for items embedded in information objects E Do not generate XML namespaces for ASN 1 modules noxmins _ Generate short form of type names shortnames 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 Stream based 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
67. can re run the compilation with the I 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 e 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 e 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 e 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 ASNIC 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 err
68. ction will convert a populated variable of the given type into an encoded ASN 1 message An encode method is only generated if it is required to alter the encoding of the base class method The Java model is built on inheritance from a set of common run time base classes These run time classes contain default implementations of encode decode methods that handle the encoding decoding of the basic types For simple assignments the generation of an encode method is not necessary For example the following production will not result in the generation of an encode method X INTEGER In this case the generated Java class extends the AsnJ Integer base class and the default encode method within this class is sufficient to encode a value of the generated type A custom encode method is only generated if 73 Generated XML Methods 1 The ASN 1 type is constructed SEQUENCE SET SEQUENCE OF SET OF or CHOICE 2 The ASN 1 type contains a testable constraint for example INTEGER 1 100 3 The ASN 1 type is enumerated This includes an INTEGER type with named numbers a BIT STRING with named bit constants or the ENUMERATED built in type Note Two variations are discussed here XER and XML The XML variant applies to EXTENDED XER See the Overview section above for more information Generated Java Method Format and Calling Parameters The signature for a Java XER encode method is as follows public
69. d and the variable type fields will be stored as open types i e as instances of Java Asn OpenType classes The user will be responsible for further decoding of the open type value 3 If the key element value is found the checkTC method will verify all fixed type values match what is defined in the key row of the object set and will fully decode all type fields according to the key row type and store the resulting decoded type in the ASN1Type fields 4 If the key element value is NOT found in the table or object set and the object set is NOT extensible then a table constraint violation exception will be thrown Simple Table Constraint 95 Table Constraint Processing 1 This function will verify all the fixed type values match what is defined in the table constraint object set If an element value does not exist in the table or object set and the object set is NOT extensible then a table constraint violation exception will be thrown Populating OpenType Variables for Encoding When tables option is used open type fields are generated as Asn Type fields The general procedure to populate the value for these fields is as follows 1 Check the possible Type in ObjectSet from index element value 2 Populate the value for this type and assign it to the open type member variable 3 Follow the common encode procedure A complete example showing how to assign open type values when table constraint code is generated is as foll
70. d because the generated table contains no information on how to encode the value 3 If the key element value is found the method will verify all fixed type values match what is defined in the key row of the object set and will also verify that the type of any variable type fields matches the expected type 4 If the key element value is not found in the table or object set and the objectset is NOT extensible then a table constraint violation exception will be thrown Simple Table Constraint 1 The checkTC method will verify that all of the fixed type values match what is defined in the table constraint object set If the element value does not exist in the table or object set and the object set is NOT extensible then a table constraint violation exception will be thrown After the checkTC method call the normal encode logic is performed For decoding the logic is reversed The normal decode logic is performed first to populate the standard and open type fields in the generated structure After that the checkTC method is invoked to perform following table constraint checks Relative Table Constraint 1 The table constraint key is searched in the object set array to find the class object for the data in the populated type variable to be encoded 2 If the key element value is NOT found and the table constraint object set is extensible the checkTC method will do no further processing i e a value field match will not be performe
71. developer tools provide the ability to convert the Java bytecode that is located in any referenced JAR files The ADT plug in handles this automatically for you If you choose not to use the plug in Android s command line tools can provide the same functionality For use with Android the ASN1C Java runtime should be either an unexpired evaluation runtime or else an unlimited runtime Your installation contains a sample Android project in java sample_ber AndroidSample Note that while this sample is located in the sample_ber folder it is really a catch all project and it is not strictly a BER only sample Problems with Dalvik VM Verifier Our Java runtime is obfuscated which means it can have some unusual but legal bytecode produced by the obfuscator Sometimes a particular JVM or in this case the Dalvik VM doesn t like bytecode that an obfuscator produces We 116 Other Java based Platforms first found this was a problem with our unlimited runtimes and so we changed our obfuscation settings If you have version 6 4 2 or later of ASNIC and are using the unlimited runtime you should not encounter verification errors Using the unlimited runtime would be the typical case for use with Android per host licensing not really being an option If however you are working with the evaluation runtime you should be sure to have ASNIC version 6 4 3 or later Note that we just discovered that the verification errors persisted in
72. e public void set_ lt elementl name gt public void set_ lt element2 name gt public void decode public int encode public void print Note 1 The notation used in the ASN 1 definition above does not represent the ASN 1 extensibility notation It is used to show a continuation of the sequence elements 2 The public and private methods that are generated are shown without arguments or function bodies for brevity The compiler generates sequential identification constants for each of the defined elements in the CHOICE construct The format used is the element names converted to all uppercase characters and preceded by an underscore The constants represent the values returned by the base class getChoiceID method can therefore be used to determine what type of choice element was received in a decode operation The getElemName method is generated by the compiler and returns the name of the selected element A series of set_ lt element gt methods are generated for setting the element value In these declarations lt element gt would be replaced with the actual element names This is the only way an element value can be set for encoding these methods ensure a consistent setting of both the element identifier and object reference values To access the value of a generated CHOICE object the getChoiceID and getElement methods within the base class are used This is generally d
73. e A code snippet showing how this could be done is as follows Step 1 Create Data and AsnlMderOutputStream objects for use in the loop Data data new Data null null null creates empty octet string objects AsnlMderOutputStream encodeStream new AsnlMderOutputStream outputStream for ACR A logic here to read name components from a DB or other medium 83 Generated MDER Encode Methods populate octet strings assume first populated by the above logic data first value first data second value second data third value third encode try second third are byte arrays name encode encodeStream useCachedLength false perhaps write some non ASN 1 data to the stream catch AsnlException e handle error 84 Chapter 11 Generated MDER Decode Methods For each ASN 1 production defined in the ASN 1 source file a decode method may be generated This method will decode an ASN 1 message into public member variables within the Java object As was the case for encode methods a decode method is only generated if it is required to alter the behavior of the base class The Java model is built on inheritance from a set of common run time base classes MDER supports only a few primitive types and most of these are subsets of ASN 1 built in types Therefore in most cases there is not an applicable MDER decode method in the common run time base c
74. e methods will be generated as well OBJECT IDENTIFIER The ASN 1 OBJECT IDENTIFIER type is converted to a Java class that extends the Asn Objectldentifier run time class This base class encapsulates the following public member variable public int value The number of subidentifiers to be encoded or that were decoded is specified in the built in length component of the array object i e value length The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt OBJECT IDENTIFIER Generated Java class public class lt name gt extends AsnlObjectIdentifier public lt name gt super public lt name gt int value_ super value_ This shows the class generated for a simple OBJECT IDENTIFIER assignment If a tagged or constrained type is specified specific encode and decode methods will be generated as well 33 ASN 1 Type to Java Class Mappings RELATIVE OID The ASN 1 RELATIVE OID type is converted to a Java class that extends the Asn 1RelativeOID run time class This class extends the Asn Objectldentifier class defined above The storage of the relative OID value is the same as described for OBJECT IDENTIFIER The only difference is the extended class defines different implementations of the encode decode methods that apply the rules associated with the RELATIVE OID type REAL The ASN 1 REAL type is converted to a Java clas
75. e ASNIC compiler has the stream option to generate encode functions of this type For each ASN 1 production defined in the ASN 1 source file a Java encode method may be generated This function will convert a populated variable of the given type into an encoded ASN 1 message The basic principles of the generation of the encode methods are the same as for ordinary BER DER encode methods Stream oriented BER encoding starts from the beginning of the message until the message is complete This is sometimes referred to as forward encoding This differs from regular BER where encoding that is done from back tofront Indefinite lengths are used for all constructed elements in the message Also there is no permanent buffer for stream oriented encoding all octets are written directly to the output stream Generated Java Method Format and Calling Parameters The signature for a Java BER stream oriented encode method is as follows public void encode AsniBerOutputStream out boolean explicit throws AsnlException java io IOException 57 Generated BER DER CER Encode Methods The out argument is a reference of an Asn BerOutputStream object that describes the output stream into which a message is being encoded This must be created and initialized before calling any encode method See the description of this class in the Java Run Time Classes section for details on how this class is used The explicit argument specifies whether or not
76. e Code Overview Element name tracking is demonstrated in the sample Writer in sample_ber EventHandler 26 Chapter 4 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 Asn Boolean 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 lt name gt BOOLEAN XSD Type lt xsd boolean gt Generated Java class public class lt name gt extends AsnlBoolean public lt name gt super public lt name gt boolean value_ super value_ This definition assumes a simple assignment of the form lt name gt BOOLEAN 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 INTE
77. e a list of java files in lt modulename gt mk Generate an Ant build script ant Generate a batch file or shell script genbuild Other Options Generate code compatible with Java 1 4 java4 Generate getter and setter methods getset 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 ASNIC 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 ASNIC from the Command Line section Compilation When all options have been specified the final screen may be used to execute the compilation command 14 Using the Compiler Compile Compilation Options Generate listing 4ist Show compilation warnings wa
78. e 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 ASN1C Project Wizard D New Project ASN1C 6 3 0 Evaluation License Project o Open Proje License expire date is Thu Apr 15 11 08 09 2010 Using the Compiler 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 amp Get Project File Name CO D cpp gt sample_ber employee v Organize v New folder E Desktop ba Name Date modified Type b Doania _ employee acp 3 16 2010 11 19AM ACP File Recent Places a Libraries Documents P Music t Pictures amp Videos jE Computer la COMPAQ C a FACTORY_IMAGI 4 File name Save as type acproj acp Hide Folders Previously saved projects may be recalled by clicking the icon next to Open an Existing Project i Load ASN1C
79. e derived from the Asn Exception base class See the section on exceptions for a complete list and description of the various exceptions that can be thrown Populating Generated Variables for Encoding Populating generated variables for encoding can be done in most cases either through the object constructors or directly by assigning an object reference to a public member variable Constructors are provided for most generated types to allow direct population of the encapsulated member variable s on initialization The exception is the classes generated for SEQUENCE OF or SET OF These only allow the size of an array to be specified population of the array elements must be done manually All of the base run time classes except Asn Null contain public member variables In practically all cases there is a single variable called value that is of the base type that needs to be populated For example the Asn1 Integer base class contains the following item public long value Therefore population of any class variable derived from INTEGER can be done by adding value to the end of the lefthand side of the assignment and an integer value on the right So for the following assignment X INTEGER A variable of the type can either be populated using the constructor with the following statement X x new X 25 or via direct access of the member variable as follows X xX new X X value 25 The only primitive type that
80. e username and password to be encoded N The encode function for Login ARGUMENT would be called and the resulting message pointer and length would be passed down to the next layer the ROSE layer W At the ROSE layer the Invoke structure would be populated with the OPERATION value invoke identifier and other header parameters The open type object used to hold the encoded parameter value from step 2 is populated by creating an Asn1OpenType object using the length of the encoded component D The encode function for Invoke would be called resulting in a fully encoded ROSE Invoke message ready for transfer across the communications link The following is a picture showing this process Application Layer Populate specific message structure Login ARGUMENT and encode Vv Encoded message pointer and length ROSE Laver Populate ROSE header message structure Invoke and encode l Open type structure contains message pointer and length from previous step Vv Final encoded message On the decode side the process would be reversed with the message flowing up the stack 1 At the ROSE layer the header would be decoded producing information on the OPERATION type based on the MACRO definition and message type Invoke Result etc The invoke identifier would also be available for use in session management In our example we would know at this point that we got a login invoke request 113 ROSE and SNMP Macro Support
81. e when we begin parsing a b and c The name of the element is passed to the event handling callback function 2 endElement This event occurs when the parser leaves a given element space Using the example above these would occur after the parsing of a b and c are complete The name of the element is once again passed to the event handling callback function 3 characters method This method is defined to pass all of the different types of primitive values that are encountered when parsing a message The primitive values are passed out in a stringified form The methods corresponding to these events are defined in Asn NamedEventHandler interface The start and end element methods are invoked when an element is parsed within a constructed type The start method is invoked as soon as the tag length is parsed in a BER or DER message The end method is invoked after the contents of the field are processed The signature of these methods is as follows void startElement String name int index 103 Event Handler Interface void endElement String name int index The name argument is used pass the element name The index argument is used for SEQUENCE OF SET OF constructs only It is used to pass the index of the item in the array This argument is set to 1 for all other constructs The characters method is used to pass out ASN 1 primitive data This is a departure from the C event handler methodology in which sep
82. ecode method to be generated Constructed types will always cause custom PER decode methods to be generated Generated Java Method Format and Calling Parameters The signature for a Java PER decode method is as follows public void decode AsnlPerDecodeBuffer buffer throws AsnlException java io Exception The buffer argument is a reference of an Asn PerDecodeBuffer object that describes the message that is being decoded This must be created and initialized before calling any decode method See the description of this class in the Java Run Time Classes section for details on how this class is used The decode method returns no result Unlike the C C version a negative status value is not returned to indicate a failure That is handled by the exception mechanism All ASN1C Java exceptions are derived from the Asn1 Exception base class See the section on exceptions for a complete list and description of the various ASN 1 exceptions that can be thrown The java io Exception that can be thrown is in the read method within the decode buffer base class This method attempts to read data from an input stream using the methods in the java io package Procedure for Calling Java PER Decode Methods The general procedure to decode an ASN 1 PER message involves the following three steps 1 Create a decode message buffer object to describe the message to be decoded 2 Invoke the decode method 3 Process the decoded data values The f
83. ectIdentifier id_ Type Type_i id id_ NOTE If the ASN 1 type name is same as the ASN 1 class name ignoring case in a single module definition then the ASN 1 class name will be changed to following lt ClassName gt _CLASS In this definition lt ClassName gt would be replaced with the name of the ASN 1 CLASS and the literal token _CLASS would be appended For example Test DEFINITION BEGIN Attribute INTEGER ATTRIBUTE ABSTRACT SYNTAX END 88 Table Constraint Processing ASNIC will change the ATTRIBUTE class name to ATTRIBUTE_CLASS to avoid conflicts with the Attribute type This automated feature will help users to successfully compile the generated code without having to manually change the name via a configuration file setting Additional Java classes are generated to create types for fields within the class definitions as follows 1 New type assignments are created for TypeField type definitions as follows _ lt ClassName gt _ lt FieldName gt lt Type gt Here ClassName is replaced with name of the Class Assignment and FieldName is replaced with name of the field Type is the type definition in the ASN 1 CLASS s TypeField This type is used as a defined type in the information object definition for absent values of the TypeField It is also useful for the user to generate a value for a related OpenType definition in a table constraint 2 New type assign
84. ects are created outside of the main decoding loop Then in the main loop these objects are reused to process each input message Data must be saved from the message type object after each iteration because the contents of the object will be overwritten on each consecutive loop iteration Nothing special needs to be done at the bottom of the loop to ready the decoder for the next message All necessary initialization will be handled internally 70 Chapter 9 Generated XML Methods Overview X 693 specifies XER XML Encoding Rules There are three variants of XER given BASIC XER often just XER for short canonical XER and EXTENDED XER Into this mix Objective Systems has added its own encoding rules which we ll call OSys XER OSys XER is very similar to XER but has a few variations that are meant to produce XML documents more closely aligned with what you might get if you were using XML Schema to specify your abstract syntax Generally OSys XER produces fewer tags The differences between these two sets of encoding rules are discussed in more detail below ASNIC supports BASIC XER canonical XER and OSys XER It has for some time supported EXTENDED XER via direct compilation of XSD In version 6 5 0 we have begun to add direct support for EXTENDED XER by adding support for some of the XER encoding instructions Nonetheless EXTENDED XER is most fully support today via direct compilation of XSD By compiling XSD you can obtain behavior
85. ed encoding methods will pass t rue to other encoding methods when appropriate As you can see the encode methods return void an exception is thrown if an error occurs All ASNIC Java exceptions are derived from Asn Exception See the section on exceptions for a complete list and description of the various exceptions that can be thrown Populating Generated Variables for Encoding Populating generated types for encoding can be done in most cases either through the constructors or by assigning object references to public member variables Constructors are provided for most generated types to allow direct population of the encapsulated member variable s on initialization The exception to this is for classes generated for SEQUENCE OF types In that case the constructors only allow the size of an array to be specified population of the array elements must be done manually 81 Generated MDER Encode Methods All of the base run time classes except Asn Null contain public member variables In practically all cases there is a single variable called value that is of the base type that needs to be populated For example the Asn1 Integer base class contains the following item public long value So for the following assignment X INTEGER 0 255 you may populate a variable of this type either using the constructor X x new X 25 or via direct access of the member variable X xX new X X value 25
86. ed to be public can be accessed directly 5 Error handling is accomplished using a try catch block to catch SAX exceptions A program fragment that could be used to decode an employee record is as follows public class Reader public static void main String args String filename employee xml String vendorParserClass org apache xerces parsers SAXParser try Create an XML reader object XMLReader reader XMLReaderFactory createxXMLReader vendorParserClass Read and decode the messag PersonnelRecord personnelRecord new PersonnelRecord personnelRecord decode reader filename if trace System out println Decode was successful personnelRecord print System out personnelRecord 0 catch Exception e System out println e getMessage e printStackTrace return 80 Chapter 10 Generated MDER Encode Methods Unlike what is done for other encoding rules for MDER we provide stream based encoding only In order to encode to a memory buffer you simply use a java io ByteArrayOutputStream For each ASN 1 production defined in an ASN 1 source file an encode method may be generated This function will convert a populated variable of the given type into an encoded ASN 1 message An encode method is only generated if it is required to alter the behavior of the base class The Java model is built on inheritance from a set of common
87. ed values These are sequential numbers starting at zero if no values are provided Otherwise the actual enumerated values are used 3 The public methods that are generated are shown without arguments or function bodies for brevity In the case of the enumerated type encode decode methods are always generated These verify that the given value is within the defined set An AsnJInvalidEnumException is thrown if the value is not in the defined set unless the enumeration is extensible In this case no exception is thrown 32 ASN 1 Type to Java Class Mappings If an extensibility marker is present in the ASN 1 definition it will not affect the generated constants A constant will be generated for all options both root and extended However in the ValueOf method an undefined constant will be returned to indicate that the value is not in the original specification NULL The ASN 1 NULL type is converted into to a Java class that extends the Asn Null run time class This base class does not contain a public member variable for a value because the NULL type has no associated value The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt NULL Generated Java class public class lt name gt extends AsnlNull public lt name gt super This shows the class generated for a simple NULL assignment If a tagged type is specified specific encode and decod
88. ed 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 At the outer level of the markup is the lt asn config gt lt asnlconfig gt 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 lt storage gt 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 15 Using the Compiler The specification of a module is done using the lt module gt lt module gt tag pair This tag pair can only be nested within the top level lt asnlconfig gt section The module is identified by using the required lt name gt lt name gt tag pair or by specifying the name as an attribute for example lt module name MyModule gt Other attributes specified within the lt module gt 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 lt production gt lt production gt tag pair This tag pair can only be nested within a lt module gt section The production is identified by
89. efinitions Variations of this are used in a number of protocols in use today including CSTA and TCAP The definition of the ROSE OPERATION MACRO that is built into the ASN1C90 version of the compiler is as follows OPERATION MACRO 5 BEGIN TYPE NOTATION Parameter Result Errors LinkedOperations VALUE NOTATION value VALUE INTEGER Parameter ArgKeyword NamedType empty ArgKeyword ARGUMENT PARAMETER Result RESULT ResultType empty Errors ERRORS ErrorNames empty LinkedOperations LINKED LinkedOperationNames empty ResultType NamedType empty ErrorNames ErrorList empty ErrorList Error ErrorList Error Error value ERROR shall reference an error value type shall reference an if no error value is specified LinkedOperationNames OperationList empty OperationList Operation OperationList Operation Operation value OPERATION shall reference an operation va type shall reference an operation ty if no operation value is specif NamedType identifier type type END This MACRO does not need to be defined in the ASN 1 specification to be parsed In fact any attempt to redefine this MACRO will be ignored Its definition is hard coded into the compiler What the compiler does with this definition is uses it to parse types and v
90. em alt 1 alt 2 etc XML decoding is accomplished by attempting to decode the content of each alternative in the union and setting the value to the first alternative that can be decoded successfully Open Type Note The X 680 Open Type replaces the X 208 ANY or ANY DEFINED BY constructs An ANY or ANY DEFINED BY encountered within an ASN 1 module will result in the generation of code corresponding to the Open Type described below The ASN 1 Open Type is converted into a Java class that extends the Asn OpenType class This class in turn extends the AsnI1 OctetString class and provides the following public member variable for storing the encoded message component public byte value The number of octets to be encoded or that were decoded is specified in the built in length component of the array object i e value length The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt lt openType gt Generated Java class public class lt name gt extends AsnlOpenType public lt name gt super public lt name gt byte data super data public lt name gt byte data int offset int nbytes super data offset nbytes public lt name gt AsnlEncodeBuffer buffer super The lt openType gt placeholder is to be replaced with any type of open type specification It could be the ANY or ANY DEFINED BY keywords from
91. es is generated for required elements only It is possible that you will not see all of these variations in a given generated class It depends on a whether or not the SEQUENCE or SET contains optional items and b whether or not it contains primitive data items For example the following shows how a variable of a generated class containing two IA5String elements could be constructed vl new HelloWorld hello world Without this second form of constructor the following would need to be done vl new HelloWorld new Asn1IA5String hello new AsnilIA5String world Also note that since all member variables are public it is not necessary to use any of the argument based constructors at all A variable can be created using the default constructor and each of the elements populated directly 36 ASN 1 Type to Java Class Mappings Creation of Temporary Types Temporary types are created when a SEQUENCE or any other constructed type definition contains other embedded constructed types An example of this is as follows EQUENCE x SEQUENCE al INTEG a2 BOOLI A S y OCT ET ST In this example the production has al and a2 RING SIZE ER EAN 10 two elements x and y The nested SEQUENCE x has two additional elements The ASNIC compiler first recursively pulls all of the embedded constructed elements out of the SEQUENCE and forms
92. essage body types An example would be the following ASN 1 type definition for a ROSE invoke message header Invoke SEQUENCE invokeID INTEGER opcode OPERATION amp operationCode argumentOPERATION amp ArgumentType 92 Table Constraint Processing This is a very simple case that purposely omits a lot of additional information such as Information Object Set constraints that are typically part of definitions such as this The reason this information is not present is because we are just interested in showing the items that the compiler is concerned with We will use this type to demonstrate the simple form of code generation We will then add table constraints and discuss what changes when the tables command line options is used The opcode field within this definition is an example of a fixed type field reference It is known as this because if you go back to the original class specification you will see that operationCode is defined to be of a specific type namely a choice between a local and global value The generated typedef for this field will contain a reference to the type from the class definition The argument field is an example of a variable type field In this case if you refer back to the class definition you will see that no type is provided This means that this field can contain an instance of any encoded type note in practice table constraints can be used with Information Object Sets to
93. essages for example a file containing multiple records or a communications device you can repeatedly invoke the MDER decode method on the given message type Note that you can also use the same instance of your message type for repeated decoding rather than creating a new object and leaving the old one to be garbage collected Nothing special needs to be done to do this The generated decode method will automatically call the internal init method before decoding to make sure all items are reset to their starting state In the example above all that would need to be done to decode a series of personnel records is the inclusion of a loop after the PersonnelRecord object was created in step 2 for 77 personnelRecord decode decodeBuffer if trace System out println Decode was successful personnelRecord print System out personnelRecord 0 86 Chapter 12 Table Constraint Processing The ASNIC Java code generator can generate code to process ASN 1 table constraints as specified in the X 681 and X 682 ASN 1 standards This code is generated through the use of the tables option This instructs the compiler to generate additional methods and tables to allow multi level message types specified using table constraints to be encoded or decoded with a single method call Special code is generated for the CLASS Information Object and Information Object Set items to create the table necessary to for table constraint
94. etails 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 Related XML Schema can be Using the Compiler Option Argument Description produced by using the xsd command line option 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 ASNIC 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 The Windows installation program should have installed an ASN1C Compiler option on your computer desktop and an ASNI1C 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 ar
95. ethod to be added to each generated class The signature of this method is as follows public boolean equals ClassName rhs where ClassName is the name of the generated class to which the member function belongs The method returns a boolean result of true if the object instances are equal and false if not Note that for classes extended from the Asn1Choice class no equals member function is generated This is because the AsnI Choice class already has an equals member function which is inherited by classes extending the Asn1 Choice class 100 Chapter 15 Generated Sample Programs The writer and reader options cause writer and reader sample programs to be generated The writer program contains sample code to populate and encode an instance of ASN 1 data The main purpose is to provide a code template to users for writing code to populate objects This is quite useful to users because generated classes can become very complex as the ASN 1 schemas become more complex The writer code also shows users how to instantiate an encode buffer object and how to use encode functions The writer program writes the encoded data to a file If the writer program is generated by using both writer and getset options then the generated writer program uses getset functions to populate data The reader program on the other hand reads the encoded data from a file It shows users how to use a decode buffer object to decode data and populate the cor
96. excessive memory allocations and garbage collection A single decode buffer object can be used to process a stream of messages If the decode message buffer is created using an input stream object that contains a series of messages for example a file containing multiple records or a communications device all that needs to be done is the continuous invocation of the BER decode method for the given message type Nothing special needs to be done to reuse the generated type object for decoding The decoder will automatically all the internal init method before decoding to make sure all items are reset to their starting state In the example above all that would need to be done to decode a series of personnel records is the inclusion of a loop after the PersonnelRecord object was created in step 2 for 77 personnelRecord decode decodeBuffer if trace System out println Decode was successful personnelRecord print System out personnelRecord 0 Deferred Decoding Another way to improve decoding performance of large messages is through the use of deferred decoding This allows for the selective decoding of only parts of a message in a single decode function call When combined with the fast copy procedure defined above this can significantly reduce decoding time because large parts of messages can be skipped Deferred decoding can be done on elements defined within a SEQUENCE SET or CHOICE construct It is done by
97. following public member variable that holds the character string contents public String value Each of the specific ASN 1 character string types except UniversalString has an associated Java class that is derived from the Asn1CharString base class The general form of the Java class name for each of the ASN 1 string types is Asn1 followed by the ASN 1 string type name For example JA5String is represented by the AsnJZA5String class NumericString by the Asn NumericString etc The UniversalString associated Java class is derived from Asn1Type and it contains the following public member that holds the character string contents public int value The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt lt CharStrType gt XSD Types lt xsd string gt and all related types including date time types and duration Generated Java class public class lt name gt extends Asnl lt CharStrType gt public lt name gt super public lt name gt String value_ super value_ ENUMERATED The ASN 1 ENUMERATED type is converted into a Java class that extends the Asn Enumerated run time class In version 6 1 the generated code was changed to conform to Joshua Bloch s static enumeration pattern as explained in Effective Java Enumerated values are created as singletons to allow for lazy initialization A specially named object 31 ASN 1 Type to Java Class Ma
98. for comparisons ncodeBuffer hexDump new PrintStream new FileOutputStream message dmp catch Exception e System out println e getMessage e printStackTrace return Reuse of Java Encoding Objects The simple example above showed the procedure to encode a single record But what if you had to decode a series of the same record over and over again This is a common occurrence in a BER encoding application You would not want to recreate the data holder and message buffer objects on each pass of the loop This would have an adverse effect on the performance of the application What you would want to do is only create the objects a single time and then reuse them to encode each message instance It turns out that this is an easy thing to do The public member variable access to the data holder object makes it easy to change the variables on each given pass And the encode buffer object contains a reset method for resetting the encode buffer for subsequent encodings The use of this method has the advantage of not releasing any of the memory that had been accumulated to this point for previous encodings To show an example of object reuse suppose we were going to encode a series of names The ASN 1 type for the names would be as follows Name APPLICATION 1 IMPLICIT SEQUENCE givenNamelA5String initial IA5String familyNamelIA5String J na The generated Java class would contain pub
99. ger base class and the default encode method within this class is sufficient to encode a value of the generated type However if the type is altered to contain a tag or constraint then a custom encode method would be generated X APPLICATION 1 INTEGER In this case special logic is necessary to apply the tag value Some types will always cause encode methods to be generated At the primitive level this is true for the ENUMERATED type This type will always contain a custom set of enumerated values All constructed types SEQUENCE SET SEQUENCE SET OF and CHOICE will cause encode methods to be added to the generated classes Generated Java Method Format and Calling Parameters The signature for a Java BER encode method is as follows public int encode AsnilBerEncodeBuffer buffer boolean explicit 53 Generated BER DER CER Encode Methods throws AsnlException The buffer argument is a reference of an Asn BerEncodeBuffer object that describes the buffer into which a message is being encoded This must be created and initialized before calling any encode method See the description of this class in the Java Run Time Classes section for details on how this class is used The return value is the length in octets of the encoded message component Unlike the C C version a negative value is never returned to indicate an encoding failure That is handled by the exception mechanism All ASN1C Java exceptions ar
100. he implementation is now complete The program can now be compiled and run When this is done the resulting output is as follows employee name givenName John initial pl familyName Smith This can certainly be improved For one thing it can be changed to print primitive values out in a name value format i e without the braces But this should provide the general idea of how it is done Example 2 An XML Converter Class The ASNIC XML Encoding Rules XER encode and decode capabilities were presented in an earlier section of this document An alternate way to create an XML document from ASN 1 data is through the event handler interface It turns out that with event handlers this conversion is fairly easy As the handler events fire all of the required symbolic data is passed out to generate an XML document The programmer is free to massage this data any way he or she wants to comply with whatever DTD or XML Schema is in use 106 Event Handler Interface The ToXML sample program demonstrates the conversion of ASN 1 data to XML using event handlers The sample is not intended to be a robust implementation it is merely designed to provide guidance in how one would go about doing this transformation The sample program can be found in the java sample_ber ToXML subdirectory within the ASNIC installation The complete class definition for the XMLHandler class is as follows class XMLH
101. he minOccurs and or maxOccurs facets Also lt xsd list gt types use this model Generated Java class public class lt name gt extends AsnlType public lt type gt elements public lt type gt elements null public lt type gt int numRecords lements new lt type gt numRecords public void decode public int encode public void print The compiler first generates a public member variable to hold the SEQUENCE OF elements The decision was made to make the variable public to make it easier to populate for encoding The alternative was to use protected or 39 ASN 1 Type to Java Class Mappings private variables with get set methods for setting or examining the values It was felt that this approach would be too cumbersome for setting values in deeply nested constructed types Two constructors are generated a default constructor and a constructor that takes a number of elements argument The default constructor will set the elements variable to null The second constructor will allocate space for the given number of elements The recommended way to populate a variable of this type for encoding is to use the second form of the constructor to allocate the required number of elements and then directly set the element object values For example to populate the following construct IntSeq SEQUENCE OF INTEGER with 3 integers the followi
102. hods in the class to write the encoded XML document to a file encodeBuffer write new FileOutputStream filename We can also directly access the buffer as follows byte buffer encodeBuffer getBuffer int msglen encodeBuffer getMsgByteCnt catch Exception e 76 Generated XML Methods System out println e getMessage e printStackTrace return An example showing stream based encoding is as follows Note personnelRecord object was previously populated with data AsnlXerOutputSteram out null try Step 1 Create an output stream object This object uses standard XER non canonical and the default internal buffer s size out new AsnlOutputStream new FileOutputStream filename Step 2 Invoke th ncode methods These include encodeStartDocument to encode the XML document header the generated Java encode method to encode the document body and the encodeEndDocument method to complete the messag Note that these methods must be invoked from within a try catch block out encodeStartDocument personnelRecord encode out null out encodeEndDocument if trace System out println Encoding was successful encodeBuffer write System out catch Exception e System out println e getMessage e printStackTrace return finally Step 3 Close
103. hrows Asn1 Exception and java io IOException leaving it to be dealt with at a higher level Finally if a message buffer is used encode buffer methods can be called to access the encoded message component The Java API provides an object called a ByteArrayInputStream that provides a way to look at the encoded component as a stream The encode buffer object provides a method called getInputStream that returns a byte array input stream representing the message component This is the preferred way to access the encoded component In addition to getInputStream there is a getMsgCopy method that will retrieve a copy of the generated message into a byte array object This is somewhat slower because a copy needs to be done Another option that is available when 75 Generated XML Methods doing XER encoding is the getBuffer method This returns a reference to the actual message buffer into which the message was encoded Since an XER message is encoded front to back unlike the back to front used in BER DER encoding the buffer reference returned will point to the start of the encoded message The getMsgLength method can then be used to get the message length in bytes Note that the byte count may not correspond to the actual character count as UTF 8 encoding is used and some characters may be multiple bytes in length If an output stream is used the stream should be closed when encoding is complete to ensure all buffered data is flushed to the out
104. ial gt lt familyName gt Jones lt familyName gt lt name gt lt dateOfBirth gt 19590717 lt dateOfBirth gt lt ChildInformation gt lt children gt lt PersonnelRecord gt Generated Decode Methods The code generated to decode XML messages is different than that of the other encoding rules This is because off theshelf XML parser software is used to parse the XML documents to be decoded This software contains a common interface known as the Simple API for XML or SAX that is a de facto standard that is supported by most parsers ASNIC generates an implementation of the content handler interface defined by this standard This implementation receives the parsed XML data and uses it to populate the structures generated by the compiler The default XML parser used for Java is the XERCES parser developed by the Apache Software Foundation http xml apache org This is open source software and implementations of the parser are available for both C and Java As mentioned since SAX is a de facto standard it should be a relatively straightforward process to use the generated handlers with any other parser 78 Generated XML Methods A diagram showing the components used in the XML decode process is as follows Step 1 Generate code Java file class MySeq AsniliInteger a ASN 1 Specification AsnlBoolean b AsnlUTF String cC SEQUENCE a INTEGER b BOOLEAN i class SaxHandler startE
105. in the above definition Instead it will include only the base types for X and Y in the generated code for the SEQUENCE Z All logic to handle the tags and constraints will be built directly into the Z encode and decode methods So the result will be only a single class generated Z that will contain an AsnJ Integer object to represent X and an Asn1OctetString object to represent Y The logic to process the application tags and the size constraint on the octet string will be generated inline in the encode and decode methods in Z 111 Chapter 20 ROSE and SNMP Macro Support The ASNIC compiler has a special processing mode that contains extensions to handle items in the older 1990 version of ASN 1 i e the now deprecated X 208 and X 209 standards This mode is activated by using the asnstd x208 commandline option Although the X 208 and X 209 standards are no longer supported by the ITU T they are still in use today This version of ASNIC contains logic to parse some common MACRO definitions that are still in widespread use despite the fact that MACRO syntax was retired with this version of the standard The types of MACRO definitions that are supported are ROSE OPERATION and ERROR and SNMP OBJECT TYPE ROSE OPERATION and ERROR ROSE stands for Remote Operations Service Element and defines a request response transaction protocol in which requests to a conforming entity must be answered with the result or errors defined in operation d
106. ins decoded data This can be accessed in nested structures by prefixing value with each of the element names from the top down For example the given name element in the Name type shown earlier would be accessed as follows name givenName value this assumes an instance of the Name class was created using the variable name name A complete example showing how to invoke a decode method is as follows try Step 1 create a decode message buffer object to describe the message to be decoded This example will use a file input stream to decode a message directly from a binary file Create an input file stream object FileInputStream in new FileInputStream filename Create a decode buffer object AsniPerDecodeBuffer decodeBuffer new AsnlPerDecodeBuffer in Step 2 create an object of the generated type and invoke the decode method PersonnelRecord personnelRecord new PersonnelRecord personnelRecord decode decodeBuffer Step 3 process the data if trace System out println Decode was successful personnelRecord print System out personnelRecord 0 catch Exception e System out println e getMessage e printStackTrace return 69 Generated PER Decode Methods Reuse of Java Decoding Objects Java objects can be reused for decoding PER messages in the same way they were for BER messages The decode buffer and message type obj
107. 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 Using the Compiler Option Argument Description genant genbuild None None Generate a build script build xml that is compatible with the Ant toolchain 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 I java4 lt directory gt None 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 Generate Java source code compa
108. into a byte array object This is somewhat slower because a copy needs to be done Another option that is only available when doing PER encoding is the getBuffer method This returns a reference to the actual message buffer into which the message was encoded Since a PER message is encoded front to back unlike the back to front used in BER DER encoding the buffer reference returned will point to the start of the encoded message The getMsgByteCnt method can then be used to get the message length in bytes or the getMsgBitCnt method can be called to get the length in bits The encode buffer class also contains other methods for operating directly on the encoded component for example the write method can be used to write it to a file or other medium And of course one could derive their own special encode buffer class from this class to add more functionality See the description of the Asn PerEncodeBuffer class in the runtime section for a full description of the available methods A complete example showing how to invoke a PER encode method is as follows Note personnelRecord object was previously populated with data 65 Generated PER Encode Methods Step 1 Create a message buffer object This object uses the default size increment for buffer expansion AsnlPerEncodeBuffer encodeBuffer new AsnlPerEncodeBuffer Step 2 Invoke th ncode method Note that it must be done from within a try catch bloc
109. ion The class is described using the following ASN 1 definition ABSTRACT SYNTAX CLASS amp id OBJECT IDENTIFIER UNIQUE amp Type property BIT STRING handles invalid encoding 0 DEFAULT WITH SYNTAX amp Type IDENTIFIED BY amp id HAS PROPERTY amp property ASN1C is used to create a meta definition for this structure The definition is stored in the file Asn AbstractSyntax java or Asn1XerAbstractSyntax java for XER An object created from the resulting Java class is populated just like any other compiler generated structure for working with ASN 1 data 89 Table Constraint Processing TYPE IDENTIFIER The ASN 1 TYPE IDENTIFIER class is a useful class definition for uniquely identifying typed data at runtime The class is described using the following ASN 1 definition TYPE IDENTIFIER CLASS amp id OBJECT IDENTIFIER UNIQUE amp Type WITH SYNTAX amp Type IDENTIFIED BY amp id The ASN 1 compiler is used to create a meta definition for this structure The definition is stored in the file AsnITypeldentifier java or AsnlXerTypeldentifier java for XER An object created from the resulting Java class is populated just like any other compiler generated structure for working with ASN 1 data Information Object NOTE Information Object code generation is only done when the tables option is selected This additional code
110. ions have the following prototypes BER DER void checkTC boolean decode PER void checkTC boolean decode boolean aligned The decode argument is used to decide if this method is to used for encoding or decoding The aligned argument is for PER and specified whether aligned or unaligned encoding decoding is in effect 94 Table Constraint Processing The purpose of these methods is to verify that the fixed values within the table constraints are what they should be and to encode or decode the open type fields using the encoder or decoder methods from the Asn1 Type objects assigned to the given table row Calls to these functions are automatically built into the standard encode or decode functions for the given type They should be considered hidden functions not for use within an application that uses the API The checkTC method will have different logic for relative and simple table constraints The logic to invoke this method is as follows On the encode side Relative Table Constraint 1 The table constraint key is searched in the object set array to find the class object for the data in the populated type variable to be encoded 2 If the key element value is NOT found and the table constraint object set is extensible the checkTC method will do no further processing i e a value field match will not be performed The user will have had to populate the type field using an Asn OpenType object in order for it to be decode
111. irst step is the creation of a decode message buffer object The Asn PerDecodeBuffer object contains constructors that can either accept a message as a byte array or as an I O input stream The input stream option makes it possible 68 Generated PER Decode Methods to decode messages directly from other mediums other than a memory buffer for example a message can be decoded directly from a file or a socket Unlike BER or DER no mechanism exists in PER to peek at an outer level tag or identifier to identify the message type This type must be known beforehand Most protocols that employ PER have a specific outer level type know as a Protocol Data Unit PDU that encompasses all of the different message types that might be received This is typically a CHOICE construct with each option representing a different type of message The generated decode method for the PDU is invoked to decode the message The calling arguments were described earlier As per the Java standard this method must be invoked from within a try catch block to catch the possible exceptions that may be thrown Alternatively the method from which the decode method is called can declare that it throws the exceptions leaving them to be dealt with at a higher level The final step is to process the data All data is contained within public member variables so access is quite easy All of the primitive data type classes contain a public member variable called value that conta
112. is table applies encodings As of this writing this is not fully supported xml used to compile ASN 1 Generated code suppports OSys XER encodings xsd produces schema that validates OSys XER encodings xml used to compile XSD Generated code supports EXTENDED XER only Differences between OSys XER and XER BASIC XER OSys XER differs from BASIC XER in the following ways e Lists of numbers enumerated tokens and named bits are expressed in space separated list form instead of as individually wrapped elements or value lists 71 Generated XML Methods For example the ASN 1 specification A SEQUENCE OF INTEGER with value 1 2 3 would produce the following encoding in XER lt A gt lt INTEGER gt 1 lt INTEGER gt lt INTEGER gt 2 lt INTEGER gt lt INTEGER gt 3 lt INTEGER gt lt A gt in XML it would be the following lt A gt 1 2 3 lt A gt e The values of the BOOLEAN data type are expressed as the lower case words true or false with no delimiters In XER the values are lt true gt and lt false gt e Enumerated token values are expressed as the identifiers themselves instead of as empty XML elements i e elements wrapped in lt gt For example a value of the ASN 1 type Colors ENUMERATED red blue green equal to red would simply be lt color gt red lt color gt instead of lt color gt lt red gt lt color gt e The special REAL values
113. k try personnelRecord encod encodeBuffer if trace System out println Encoding was successful System out printin Hex dump of encoded record ncodeBuffer hexDump System out printin Binary dump encodeBuffer binDump personnelRecord Step 3 Access th ncoded message component In this case we use methods in the class to write the component to a file and output a formatted dump to the message dmp f filer Write th ncoded record to a file encodeBuffer write new FileOutputStream filename Generate a dump file for comparisons ncodeBuffer hexDump new PrintStream new FileOutputStream message dmp We can also directly access the buffer as follows byte buffer encodeBuffer getBuffer int msglen encodeBuffer getMsgByteCnt catch Exception e System out println e getMessage e printStackTrace return If you compare this example with the BER encoding example in Figure 2 you will see the encoding procedure is almost identical This makes it very easy to switch encoding methods should the need arise All you need to do is change Asn1BerEncodeBuffer to Asn PerEncodeBuffer and remove the explicit argument from the encode method call Reuse of Java Encoding Objects The concept of reusing Java objects for PER encoding is the same as was described previously for BER encoding Basically all that needs t
114. l as it will shrink the output considerably while allowing them fine control over decoding procedures 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 12 Using the Compiler XSD Generation Options E Generate Application Information Annotations Tags Enumerations Extensions E Generate Non native Attribute Annotations Specify the Target XML Namespace V Reference Types in the asn1 xsd schema These options are described in Running ASNIC 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 13 Using the Compiler Java Code Generation Options Code Organization Output code to directories based on module names dirs Specify package name pkgname Specify package prefix pkgpfx Build Options Generat
115. lass 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 lt tag gt 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 lt tag gt is encountered The ASNIC 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 Error Handling As noted elsewhere in this manual the asn1c runtime and generated code will throw exceptions that are or derive from Asn1Exception The exception tells you what was wrong and provides a stack trace If you need additional information you may try the following e Identify the byte location in the input data using Asn1DecodeBuffer getB yteCount e Identify the problem element using element name tracking The procedure to do this is simple 1 Add events to your asnlc command line This is necessary for element name tracking to work 2 Obtain an Asn1Context object from your encode decode buffer using Asn MessageBuffer getContext 3 Enable element name tracking before encoding decoding by invoking Asn1Context enableElementTracking 4 Get the name of the problem element by invoking Asn1Context getCurrentElement inside your exception handling code 25 Generated Java Sourc
116. lass and so a decode method will be generated Generated Method Format and Calling Parameters The signature for an MDER decode method is as follows public void decode AsniMderDecodeBuffer buffer throws AsnlException java io IOException The buffer argument is an Asn MderDecodeBuffer object which provides the message to be decoded This must be created and initialized before calling any decode method See the description of this class in the Java Run Time Classes section for details on how this class is used As you can see the decode method returns void the data is decoded into the instance on which decode is invoked and an exception is thrown if an error occurs All ASNIC exceptions are derived from Asn Exception See the section on exceptions for a complete list and description of the various ASNIC exceptions that can be thrown Procedure for Calling Java MDER Decode Methods The general procedure to decode an ASN 1 MDER message involves the following three steps 1 Create a decode buffer on the message to be decoded 2 Invoke the decode method 3 Process the decoded data values The first step is the creation of a decode buffer Asn MderDecodeBuffer has a constructor that accepts messages stored in a byte array It also has a constructor that accepts a java io InputStream so that messages may be streamed from various sources such as from a file The second step is to invoke the generated decode method The calling a
117. le constraint In the case of PER only the latter condition will cause a custom method to be generated The reason is because PER basically ignores the tags on tagged types and they therefore have no effect on the final decoded message component For example the following declaration will cause a custom encode method to be generated because the value range constraint is a PER visible that will alter the encoding X INTEGER 1 255 In this case special logic is necessary to apply the value range constraint Some types will always cause encode methods to be generated At the primitive level this is true for the ENUMERATED type This type will always contain a custom set of enumerated values All constructed types SEQUENCE SET SEQUENCE SET OF and CHOICE will cause encode methods to be added to the generated classes Generated Java Method Format and Calling Parameters The signature for a Java PER encode method is as follows public void encode AsnlPerEncodeBuffer buffer throws AsnlException java io IOException The buffer argument is a reference of an Asn PerEncodeBuffer object that describes the buffer into which a message is to be encoded This must be created and initialized before calling any encode method See the description of this class in the Java Run Time Classes section for details on how this class is used The PER encode methods do not return a value This is different than the C C version tha
118. lement c UTF8String characters on endElement Step 2 Build Application lt MySeq gt lt a gt 22 lt a gt 22 lt b gt lt true gt lt b gt true lt c gt Hello lt c gt Hello lt MySeq gt ASN1C generated SAX handlers ASNIC generates code to implement the following methods defined in SAX content handler interface startElement characters endElement The interface defines other methods that can be implemented as well but these are sufficient to decode XER encoded data These methods are added to an inner SAX handler class generated for each ASN 1 production The procedure to invoke the generated decode method is similar to that for the other encoding rules It is as follows 1 Instantiate an XMLReader object The XML parser interface should provide a factory method for creating an object of this type for any vendor specific XML parser implementation 2 Instantiate a generated Java lt ProdName gt object to hold the decoded message data 3 Invoke the lt ProdName gt object decode method passing the reader created in step 1 and the URI of the XML document to be parsed This method initiates and invokes the XML parser s parse method to parse the document This in turn invokes the generated SAX handler methods 79 Generated XML Methods 4 Methods within the lt ProdName gt object can now be used to access the decoded data The member variables that were declar
119. lic member variables for each of the string objects public AsnlIA5String givenName public AsnlIA5String initial public AsnlIA5String familyName The most efficient way to repopulate these variables within a loop would be simply to assign each of the new strings to be encoded directly to the public value member variables contained within the Asn ZA5String objects i e the Name or AsnIIA5String objects should not be reconstructed each time A code snippet showing how this could be done is as follows Step 1 Create Name and AsnlBerEncodeBuffer objects for use in the loop Name name new Name creates empty string objects AsnlBerEncodeBuffer encodeBuffer new AsnlBerEncodeBuffer 56 Generated BER DER CER Encode Methods for logic here to read name components from a DB or other medium populate string variables assume stringl 2 and 3 are string variables read from DB above name givenName value stringl name initial value string2 name familyName value string3 encode try len name encod encodeBuffer true do something with th ncoded message component reset encode buffer for next pass ncodeBuffer reset catch AsnlException e handle error Stream Oriented Indefinite Length Encode Methods BER messages can be encoded directly to an output stream such as a file network or memory stream Th
120. list of these exceptions can be found in the ASNIC Exceptions section The general form of a PER encode method is as follows public void encode AsnlPerEncodeBuffer 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 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 AsnlXerEncoder 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 Asn1 XmlEncoder interface The element name is the name of the element that is to bracket the XML encoded value i e lt elemName gt value lt elemName gt The method return type is void because errors are reported through the exception mechanism Other Methods Other generated methods include the following get lt Element gt set lt Element gt Public get set methods are generated for each element within a container type SEQUENCE SET CHOICE if the getset command line s
121. lso contains other methods for operating directly on the encoded component for example the write method can be used to write it to a file or other medium And of course one could derive their own special encode buffer class from this class to add more functionality See the description of the Asn BerEncodeBuffer class in the run time section for a full description of the available methods A complete example showing how to invoke an encode method is as follows Note personnelRecord object was previously populated with data Step 1 Create a message buffer object This object uses the default size increment for buffer expansion AsnlBerEncodeBuffer encodeBuffer new AsnlBerEncodeBuffer Step 2 Invoke th ncode method Note that it must be done from within a try catch block ery personnelRecord encode encodeBuffer true if trace System out println Encoding was successful System out printin Hex dump of encoded record ncodeBuffer hexDump System out printin Binary dump encodeBuffer binDump Step 3 Access th ncoded message component In this case we use methods in the class to write the component to a file and output a formatted dump to the message dmp file 55 Generated BER DER CER Encode Methods Write th ncoded record to a file encodeBuffer write new FileOutputStream filename Generate a dump file
122. me gt lt IA5String gt Jones lt IA5String gt lt familyName gt lt name gt lt dateOfBirth gt lt IA5String gt 19590717 lt IA5String gt lt dateOfBirth gt lt element gt lt children gt lt PersonnelRecord gt Add an XML document header and you should be able to display this data in XML enabled browser 109 Chapter 18 IMPORT EXPORT of Types ASNIC allows productions to be shared between different modules through the ASN 1 IMPORT EXPORT mechanism The compiler parses but ignores the EXPORTS declaration within a module As far as it is concerned any type defined within a module is available for import by another module When ASNIC sees an IMPORT statement it first checks its list of loaded modules to see if the module has already been loaded into memory If not it will attempt to find and parse another source file containing the module The logic for locating the source file is as follows 1 The configuration file if specified is checked for a lt sourceFile gt element containing the name of the source file for the module 2 If this element is not present the compiler looks for a file with the name lt ModuleName gt asn where module name is the name of the module specified in the IMPORT statement In both cases the I command line option can be used to tell the compiler where to look for the files The other way of specifying multiple modules is to include them all within a single
123. ments are created for ValueField or ValueSetField type definitions if the type is with a constraint definition and or the type is Sequence Set Choice Sequenceof SetOf definition _ lt ClassName gt _ lt FieldName gt lt Type gt Here ClassName is replaced with name of the Class Assignment and FieldName is replaced with name of the ValueField or ValueSetField Type is the type definition in The ASN 1 CLASS s ValueField or ValueSetField This type will appear as a defined type in the ASN 1 CLASS s ValueField or ValueSetField This new type assignment is used for compiler internal code generation purpose It is not designed for use by the end user 3 New value assignments are created for ValueField default value definitions as follows _ lt ClassName gt _ lt FieldName gt _default lt Type gt lt Value gt Here ClassName is replaced with name of the Class Assignment and FieldName is replaced with name of the ValueField Value is the default value in the ASN 1 CLASS s ValueField amp Type is the type in the ASN 1 CLASS s ValueField This value is used as a defined value in the information object definition for an absent value of the field This new value assignment is used for compiler internal code generation purpose It is not designed for use by the end user ABSTRACT SYNTAX The ASN 1 ABSTRACT SYNTAX class is a useful class definition used to declare the top level protocol data units PDU s defined within a specificat
124. n we simply indent this is another private method within the class and print out the name equal sign and opening brace We then increment the indent level Logic is also present to check the index value to see if it is zero or greater If it is an array subscript is added to the element name In endElement we simply terminate our brace block as follows 105 Event Handler Interface public void endElement String name int index mindentSpaces 3 indent System out printin The characters method simply indents and prints the stringified value public void characters String svalue short typeCode indent System out println svalue That completes the PrintHandler class implementation Next we need to create an object of the class and register it prior to invoking the decode method In the Reader java program the following lines do this Register event handler object PrintHandler printHandler new PrintHandler personnelRecord decodeBuffer addNamedEventHandler printHandler The addEventHandler method defined in the Asn DecodeBuffer base class is the mechanism used to do this Note that event handler objects can be stacked Several can be registered before invoking the decode function When this is done the entire list of event handler objects is iterated through and the appropriate event handling callback function invoked whenever a defined event is encountered T
125. n X 694 XSL None syntax check only BER DER CER XER T XML select aligned or unaligned PER at run time Code Options V Generate code for all dependent imported type definitions Generate code compatible with compiler version 6 2 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 10 Using the Compiler Common Code Generation Options Language Options Function Options Utility Options Generated Function Types V Encode P Print Functions V Decode E Stream Print Format Constraints Do not generate constraint checks 4ax Enable strict constraint checks strict Generate code to handle table constraints ta
126. n that we created is as follows class PrintHandler implements AsnliNamedEventHandler 104 Event Handler Interface protected String mVarName protected int mIndentSpaces 0 public PrintHandler String varName mVarName varName System out printin mIndentSpaces 3 mVarName public void startElement indent System out print if index gt 0 System out print index System out println mIndentSpaces 3 String name name oa Nee ae public void endElement mIndentSpaces 3 indent System out printin String name cg public void characters indent System out printin String svalue svalue private void indent for int i 0 i lt mIndentSpaces System out print i int index int index short typeCode In this definition we chose to add the mVarName and mIndentSpaces member variables to keep track of these items The user is free to add any type of member variables he or she wants The only firm requirement in defining this class is the implementation of the methods defined in the interface We implement these methods as follows public void startElement int index indent System out print if index gt 0 System out print index System out println mIndentSpaces 3 String name name EA ta He In this simplified implementatio
127. nd However if a parser is not found then the compiler will use XERCES_ROOT instead of the parser root directory An error message will be printed and the user will update the file accordingly 102 Chapter 17 Event Handler Interface The events command line switch causes hooks for user defined event handlers to be inserted into the generated Java decode methods What these event handlers do is up to the user They fire when key message processing events occur during the course of parsing an ASN 1 message They are similar in functionality to the Simple API for XML SAX that was described earlier for parsing XML messages How It Works Users of XML parsers are probably already quite familiar with the concepts of SAX Significant events are defined that occur during the parsing of a message As a parser works through a message these events are fired as they occur by invoking user defined callback functions These callback functions are also known as event handler functions A diagram illustrating this parsing process is as follows Parser ASN 1 decode function The events are defined to be significant actions that occur during the parsing process We will define the following events that will be passed to the user when an ASN 1 message is parsed 1 startElement This event occurs when the parser moves into a new element For example if we have a SEQUENCE a b c construct type names omitted this event will fir
128. nd formatting the information field references within standard type structures The second form is selected by specifying the tables command line option To better understand the support in this area the individual components of Information Object specifications are examined We begin with the CLASS specification that provides a schema for Information Object definitions A sample class specification is as follows OPERATION CLASS amp operationCode CHOICE local INTEGER global OBJECT IDENTIFIER amp ArgumentType amp ResultType amp Errors ERROR OPTIONAL Users familiar with ASN 1 will recognize this as a simplified definition of the ROSE OPERATION MACRO using the Information Object format When a class specification such as this is parsed information on its fields is maintained in memory for later reference In the simple form of code generation the class definition itself does not result in the generation of any corresponding Java code It is only an abstract template that will be used to define new items later on in the specification In the table form a Java container class is generated to hold the Information Object instances of the ASN 1 CLASS Fields from within the class can be referenced in standard ASN 1 types It is these types of references that the compiler is mainly concerned with These are typically header types that are used to add a common header to a variety of other m
129. new lt ElemType gt lt elemlvalue gt new lt ElemType gt lt elem2value gt For example consider the following declaration SeqOfType SEQUENCE OF INTEGER value SeqOfType 1 2 This would result in the following Java constant being generated for value public static final SeqOfType value new SeqOfType new AsnlInteger 1 new AsnlInteger 2 SET OF Value Specification The value code generation for the ASN 1 SET OF type is that same as that for SEQUENCE OF described above CHOICE Value Specification A CHOICE value specification causes a final static instance of the Java class generated for the CHOICE to be generated 51 ASN 1 Type to Java Class Mappings ASN 1 production lt name gt lt ChoiceType gt elemname lt elemvalue gt Generated Java constants public static final lt ChoiceType gt lt name gt new lt ChoiceType gt lt ElemCode gt new lt ElemType gt lt elemvalue gt For example consider the following declaration ChoiceType CHOICE oid OBJECT IDENTIFIER id INTEGE value ChoiceType id 1 This would result in the following Java constant being generated public static final ChoiceType value new ChoiceType ChoiceType _ID new AsnlInteger 1 52 Chapter 5 Generated BER DER CER Encode Methods Two different types of BER Basic Encoding Rules encode me
130. ng code could be used IntSeq intSeq new IntSeq 3 intSeq elements 0 new AsnlInteger 1 intSegq elements 1 new AsnlInteger 2 intSegq elements 2 new AsnlInteger 3 Note that each of the integer element values is wrapped in an AsnJInteger wrapper class Generation of Temporary Types for SEQUENCE OF Elements As with other constructed types the lt type gt variable can reference any ASN 1 type including other ASN 1 constructed types Therefore it is possible to have a SEQUENCE OF SEQUENCE SEQUENCE OF CHOICE etc When a constructed type is referenced a temporary type is generated for use in the final production The format of this temporary type name is as follows lt prodName gt _element In this definition lt prodName gt refers to the name of the production containing the SEQUENCE OF type For example a simple and very common single level nested SEQUENCE OF construct might be as follows A SEQUENCE OF SEQUENCE INTEGER a BOOLEAN b In this case a temporary type is generated for the element of the SEQUENCE OF construct This results in the following two equivalent ASN 1 types A element SEQUENCE INTEGER a BOOLEAN b A SEQUENCE OF A element These types are then converted into the equivalent Java classes using the standard mapping that was previously described SEQUENCE OF Type Elements in Other Constructed Types
131. o be done is the creation of a single PER encode buffer object and an object corresponding 66 Generated PER Encode Methods to the ASN 1 data type to be encoded outside of the processing loop These objects can then be reused to encode each instance of the messages to be sent After each message is encoded the PER buffer must be reset for the next message by using the reset method See the section on reuse of objects in the BER encoding section for a more thorough discussion and sample code on using this capability 67 Chapter 8 Generated PER Decode Methods For each ASN 1 production defined in the ASN 1 source file a Java decode method may be generated This method will decode an ASN 1 message into public member variables within the Java object As was the case for encode methods a decode method is only generated if it is required to alter the default method in the base class The Java model is built on inheritance from a set of common run time base classes These run time classes contain default implementations of encode decode methods that handle the encoding decoding of the basic types For primitive types a custom PER decode method is only generated if one or more of the following is true 1 The type contains a PER visible constraint 2 The generation of event handlers was specified The exception to this rule is the ENUMERATED primitive type or likewise INTEGER type with a named number list that will always cause a d
132. objective SYSTEMS INC ASNIC ASN 1 Compiler Version 6 5 Java Users Guide Reference Manual Objective Systems Inc version 6 5 May 2014 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 2012 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 1 Overview of ASNIG for Java ere missni i eia e a a E oe sods sees ro saibereianaeania sea IEE 1 2 Using the Compiler iei rosier eoi EE EEEE Go ie cade LENSE sk EEEE TRG ee E ee eevee sods Sees TNS 2 Running ASNI C ij ccs uses oases anaes r CEE aE EO E EEEE EEO EE coven dbbeasauss eeaitedseveseudesvetsagsverbe 2 ASNIC Java Command Line Options 2 0 0 0 cece cece cece cece cece cece cena ceneeeneceeeeeeseeeeaeseaesea esau sean eeags 2 Using the GUI Wizard to Run ASNIC scission oaia seatg aes batts a T E Ta tes 7 Using Projects ei eccc5c6 ioc Meese ances ey cbse aE OEE E gestae E S cs aves E EEEE EEE E SE 7 Common Code Generation Options 2 2 5 csscssisseccsegasdocs sass TEE seeder sievccsspesoveesieedeassasestaaas
133. oded decoded This release of ASNIC 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 e ASNIC C C Compiler User s Manual C C code generation e ASNIC 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 ASNIC 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 e Basic Encoding Rules BER Distinguished Encoding Rules DER and Canonical Encoding Rules CER as published in the ITU T X 690 standard e Packed Encoding Rules PER as published in the ITU T X 691 standard e XML Encoding Rules XER
134. 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 AsnlBerDecodeBuffer 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 Asn BerDecodeBuffer 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 t rue and the implicitLength argument set to zero These arguments are 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 AsnlException java io IOException The AsnJ Exception class is the base class for all exceptions defined for ASNIC A complete list of these exceptions can be found in the ASNIC Exceptions section For PER the
135. one with an if or switch statement as follows Asn1iBMPString element if aliasAddress getChoiceID AliasAddress _H323_ID element AsnlBMPString aliasAddress getElement In this case getChoiceID is invoked and the result tested to see if the expected value was received If it was the element is assigned using getElement with a cast operation 42 ASN 1 Type to Java Class Mappings Creation of Temporary Types The rules for the generation of CHOICE temporary type variables are the same as they were for SEQUENCE and SET variables Complex nested types are pulled out of the definitions and used to create additional types to reduce the nesting levels An example of this is as follows TestChoice CHOICE a INTEGER b BOOLEAN c SEQUENCE aa IA5String bb NULL This would be reduced to the following equivalent ASN 1 productions TestChoice c SEQUENCE aa IA5String bb NULL TestChoice CHOICE a INTEGER b BOOLEAN c TestChoice c In this case the embedded constructed element for option c was pulled out to form the TestChoice c production and then this new production is referenced in the original definition Populating Generated Choice Structures for Encoding The only way a CHOICE construct can be populated for encoding is by using one the generated set_ lt element gt methods It is necessary to do it this way because
136. onnelRecord gt lt name gt lt givenName gt lt IA5String gt John lt IA5String gt lt givenName gt lt initial gt lt IA5String gt P lt IA5String gt lt initial gt lt familyName gt lt IA5String gt Smith lt IA5String gt lt familyName gt lt name gt lt number gt lt INTEGER gt 51 lt INTEGER gt lt number gt lt title gt lt IA5String gt Director lt IA5String gt lt title gt lt dateOfHire gt 108 Event Handler Interface lt IA5String gt 19710917 lt IA5String gt lt dateOfHire gt lt nameOfSpouse gt lt givenName gt lt IA5String gt Mary lt IA5String gt lt givenName gt lt initial gt lt IA5String gt T lt IA5String gt lt initial gt lt familyName gt lt IA5String gt Smith lt IA5String gt lt familyName gt lt nameOfSpouse gt lt children gt lt element gt lt name gt lt givenName gt lt IA5String gt Ralph lt IA5String gt lt givenName gt lt initial gt lt IA5String gt T lt IA5String gt lt initial gt lt familyName gt lt IA5String gt Smith lt IA5String gt lt familyName gt lt name gt lt dateOfBirth gt lt IA5String gt 19571111 lt IA5String gt lt dateOfBirth gt lt element gt lt element gt lt name gt lt givenName gt lt IA5String gt Susan lt IA5String gt lt givenName gt lt initial gt lt IA5String gt B lt IA5String gt lt initial gt lt familyNa
137. onstructor contains a size increment argument This argument will determine how often the buffer will need to be resized to hold large messages If you know that you will be encoding large messages then this object should be constructed with a large value for the increment If you know that you will be encoding small messages in a constrained environment then this value can be set very low The default constructor sets the value to a reasonable mid range value see SIZE_INCREMENT in Asn EncodeBuffer java as of this writing the value was set to 1024 The second step is the invocation of the encode method The calling arguments were described earlier As per the Java standard this method must be invoked from within a try catch block to catch the possible exceptions that may be thrown Alternatively the method from which the encode method is called can declare that it throws an Asn Exception leaving it to be dealt with at a higher level Finally encode buffer methods can be called to access the encoded message component The Java API provides an object called a ByteArrayInputStream that provides a way to look at the encoded component as a stream The encode buffer object provides a method called getInputStream that returns a byte array input stream representing the message component This is the preferred way to access the encoded component In addition to getInputStream there is a getMsgCopy function that will retrieve a copy of the generated message
138. ors A single error message is output to stderr after compilation on the unit is complete to indicate error conditions exist 19 Chapter 3 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 asnlj runtime import java
139. our evaluation runtime while in the midst of packaging and releasing our 6 4 3 kits As a result we repackaged those kits If you have an ASNIC 6 4 3 evaluation kit you should not encounter verification errors on Android If you do and you were an early adopter of 6 4 3 you may just need to re download the evaluation kit This is likely the case if your runtime JAR file is dated before August 12 2011 117
140. ource file is a tag constant This is only generated if the production is tagged The runtime class Asn Tag 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 AsnI Integer 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 givenNamelA5String initial IA5String familyNamelIA5String 7 na will result in the following public member variables being added to the generated class public AsnlIA5String givenName public AsnlIA5String initial public AsnlIA5String 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 u
141. ows ATTRIBUTE CLASS amp Type amp id OBJECT IDENTIFIER UNIQUE WITH SYNTAX WITH SYNTAX amp Type ID amp id name ATTRIBUTE WITH SYNTAX VisibleString ID 011 commonName ATTRIBUTE WITH SYNTAX INTEGER ID O 1 2 name commonName A SupportedAttributes ATTRIBUTI Invoke SEQUENCE opcode ATTRIBUTE amp id SupportedAttributes argument ATTRIBUTE amp Type SupportedAttributes opcode In the above example the Invoke type contains a relative table constraint Its element opcode refers to the ATTRIBUTE class s id field and the argument element refers to ATTRIBUTE class s Type field The opcode element is the index element into the SupportedAttributes information object set The argument element is an open type but its type must match that specified at the location in the SupportedAttributes information object set indexed by opcode In this example opcode can have only two possible values 0 1 1 or 0 1 2 If the opcode value is 0 1 1 then argument must be a value of type VisibleString If the opcode value is 0 1 2 then argument will have an INTEGER value Any other value of the opcode element will be a violation of the Table Constraint If the SupportedAttributes object set was extensible in this example it is not then the argument element can be a value of any type In this case if the user is using
142. pen type value id value and using it as a source for a new Asn BerDecodeBuffer The element can then be decoded by creating a new object for the element in this case a new instance of Asn Objectldentifier and calling its decode method 63 Chapter 7 Generated PER Encode Methods The generation of methods to encode data in accordance with the Packed Encoding Rules PER is similar to how methods were generated in the BER DER case discussed previously For each ASN 1 production defined in the ASN 1 source file a Java encode method may be generated This function will convert a populated variable of the given type into an encoded ASN 1 message An encode method is only generated if it is required to alter the encoding of the base class method The Java model is built on inheritance from a set of common run time base classes These run time classes contain default implementations of encode decode methods that handle the encoding decoding of the basic types For simple assignments the generation of an encode method is not necessary For example the following production will not result in the generation of an encode method X INTEGER In this case the generated Java class extends the AsnJ Integer base class and the default encode method within this class is sufficient to encode a value of the generated type In the case of BER DER a custom encode method was generated if a the type was tagged or b it contained a testab
143. ppings dec is created to hold decoded values In combination these changes improve application performance since only a fixed number of objects are allocated for any execution of the application The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt ENUMERATED lt el gt lt e2 gt lt en gt XSD Types Any type with an lt xsd enumeration gt restriction Generated Java class public class lt name gt extends AsnlEnumerated private static lt name gt lt el gt null private static lt name gt lt e2 gt null private static lt name gt dec new lt name gt 1 protected lt name gt int value_ super value_ public static lt name gt lt el gt if lt el gt null lt el gt new lt name gt lt v1 gt return lt el gt public static lt name gt valueOf int value_ protected static lt name gt dec return dec public void decode public int encode public void print Note 1 The notation used in the ASN 1 definition above does not represent the ASN 1 extensibility notation It is used to show a continuation of the enumerated sequence of values 2 The lt el gt lt e2 gt etc items denote enumerated constants These can be in identifier only format or identifier value format The lt v1 gt lt v2 gt etc items denote the enumerat
144. put device The Asn1lXerEncodeBuffer encode buffer class also contains other methods for operating directly on the encoded component for example the write method can be used to write it to a file or other medium A user could also derive their own special encode buffer class from this class to add more functionality See the description of the Asn1XerEncodeBuffer class in the run time section for a full description of the available methods A complete example showing how to invoke an XER encode method is as follows Note personnelRecord object was previously populated with data Step 1 Create a message buffer object This object uses standard XER non canonical and the default size increment for buffer expansion AsnlXerEncodeBuffer encodeBuffer new AsnlXerEncodeBuffer Step 2 Invoke th ncode methods These include encodeStartDocument to encode the XML document header the generated Java encode method to encode the document body and the encodeEndDocument method to complete the messag Note that these methods must be invoked from within a try catch block Ery f ncodeBuffer encodeStartDocument personnelRecord encode encodeBuffer null ncodeBuffer encodeEndDocument if trace System out println Encoding was successful encodeBuffer write System out Step 3 Access th ncoded message component In this case we use met
145. r to calling the generated decode method for a particular type The best way to illustrate this procedure is through examples We will first show a simple event handler application to provide a customized formatted printout of the fields in a BER message Then we will show a simple XML converter class that will convert the data in a BER message to XML Example 1 A Formatted Print Handler The ASNIC evaluation and distribution kits include a sample program for doing a formatted print of parsed data This code can be found in the java sample_ber EventHandler directory Parts of the code will be reproduced here for reference but refer to this directory to see the full implementation The format for the printout will be simple Each element name will be printed followed by an equal sign and an open brace and newline The value will then be printed followed by another newline Finally a closing brace followed by another newline will terminate the printing of the element An indentation count will be maintained to allow for a properly indented printout We will first create a class called PrintHandler that implements the Asn NamedEventHandler interface and handles the formatted printing of the data The rule for the implementation of interfaces is that you must provide an implementation for each of the methods listed That is it You can add as many additional methods member variables etc that you like The PrintHandler implementatio
146. re 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 lt listclass gt lt listclass gt Java List Class This instructs the compiler to use a different class than the default LinkedList it would be possible for example to use jJava util ArrayList Element Level These attributes can be applied at the element level by including them within a lt element gt section Name Values Description lt isOpenType gt This flag variable specifies that this element will be decoded as an open type i e skipped Refer to the section on deferred decoding for further information Note that this variable can only be used with BER CER or DER encoding rules 18 Using the Compiler 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 ASNIC 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
147. re 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 lt module gt section Name Values Description lt name gt module name This attribute identifies the module lt name gt to which this section applies It is required lt include types names ASN 1 type or values names are This item allows a list of ASN 1 values names gt 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 element types in a SEQUENCE SET or CHOICE all of the dependent types will be automatically included as well lt include importsFrom name gt ASN 1 module name s specified as an attribute list This form of the include directive tells the compiler to only include types and or values in the generated code that are imported by the given module s lt exclude values names gt types names ASN 1 type or values names are specified as an attribute list This item allows a list of ASN 1 types and or values to be excluded in
148. responding class object On successful decode it prints the decoded data to standard output 101 Chapter 16 Generated Build Script The genbuild option causes a build script to be generated This script can be used to Java compile the generated source files For Windows the w32 command line option should be specified along with genbuild to generate a DOS batch file bat This file is named build bat For Linux UNIX a shell script is generated The name of this file is build sh When a build script is generated it is assumed that the ASNIC project exists within the ASNIC installation directory tree The generation logic tries to determine the root directory of the installation by traversing upward from the project directory in an attempt to locate the java subdirectory which is assumed to be the installation root directory If the project is located outside of the ASNIC hierarchy the user can set the OSROOTDIR environment variable to point at the root directory If the root directory is located successfully the generated build script will use that directory however if the compiler fails to find the installation root directory it will use ROOT_DIR instead and print an error message Users will have to manually replace ROOT_DIR with the actual compiler installation root directory Also for the xer or xml option along with genbuild an XML parser is required The compiler will try to locate a parser and use it if fou
149. rguments were described earlier The final step is to apply your application specific processing to the data All data is contained within public member variables so access is quite easy A complete example showing how to invoke a decode method is as follows try 85 Generated MDER Decode Methods Step 1 create a decode buffer for the message to be decoded This example will use a file input stream to decode a messag in a binary file Create an input file stream objec FileInputStream ins new FileInputS cv a ream filename Create a decode buffer object AsniMderDecodeBuffer decodeBuffer new AsniMderDecodeBuffer ins Step 2 create an object of the generated type and invoke the decode method PersonnelRecord personnelRecord new PersonnelRecord personnelRecord decode decodeBuffer Step 3 process the data if trace System out println Decode was successful personnelRecord print System out personnelRecord 0 catch Exception e System out println e getMessage e printStackTrace return Reuse of Java Decoding Objects The sample above showed the MDER decoding of a single message In a typical application a loop would be involved to decode a series of messages A single decode buffer can be used to process a stream of messages If the decode buffer is created using an input stream that contains a series of m
150. rnings Compilation command C acv630 pin asn 1c C acv630 cpp sample_ber employee employee asn O C acv630 cpp sample_ber employee useAsn 1Xsd ber per xml xsd cpp depends ist warnings a Save Project T compile Finish Cancel 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 reus
151. run time base classes MDER supports only a few primitive types and most of these are subsets of ASN 1 built in types Therefore in most cases there is not an applicable MDER encode method in the common run time base class and so an encode method will be generated The generated classes for all constructed types SEQUENCE SEQUENCE OF and CHOICE will include generated encode methods Generated Method Format and Calling Parameters The signature for the MDER encode method comes in two forms shown below public void encode AsniMderOutputStream buffer boolean useCachedLength throws AsnlException java io IOException public void encode AsniMderOutputStream buffer throws AsnlException java io IOException The buffer argument is an Asn MderOutputStream object which receives the encoded message This must be created and initialized before calling any encode method See the description of this class in the Java Run Time Classes section for details on how this class is used The useCachedLength argument indicates whether the encode method can rely on cached length information In some cases MDER requires pre calculation of the length of nested structures and this piece of information is needed twice during encoding once when encoding the containing structure and once when encoding the nested structure The generated types cache this information during encoding User code should normally pass false for this argument The generat
152. s 87 CLASS specificato siria an e A aE ls ode Beds O E E del E S ENR 87 Data Member Generations yeni rore eth ein E ak AE REE A E a aks EA N Re 87 Method and Constructor Generation ccccccceceec ence eee neeeecneceecneceeeseeeececeeeeneseeeeseetesenenesenes 88 ABSTRACT SYNTAX cesen EEE EAE E EEE EEEE EOS EEEE ERTE 89 TYPEJDENTIFIER crre aroe E R E God ae ANOO OE R dan ab S E 90 Intorm ton ODJeCt ss ensanse a e E E E a NE En A E dase ERA SEE 90 Intormation Object Set treimea a E T eat ced iby S E T E T A EA a 91 Generated Information Object Table Structure seeiseseseeeeserrerresrrerterertrrrtrertertrerrterreereerreerrete 92 Simple Form Code Generation sosisini R a E E a E I R E E TES 93 Table Form Code Generation soia nenene e a Ea RE E S RE AE EE S 93 Additional Code Generated for the tables Option 0 10 0 ccccccccee cece cnee cece cece tena een eeneceeeeeneenes 94 Populating OpenType Variables for Encoding ccc cee cc ence eece ence eeeeeeeeeeeeeeeaeeeaeeea teen sean ecue cogs 96 Decoding Types with Table Constraints 0c cceeceee cece cece E EE E E EEE EEE EE EE S 97 13 Generated Prnt Methods set nenes ob tives eb aes dew eedaecyoee nceaeus tens send AEE R AN EE gos ceaweeey 98 Generated Java Method Format and Calling Parameter cccccecceece ence eeceeeceeeceeeea seca eeaa sean eeaes 98 14 Generated Compare Methods sser sses ves dysheunedsne se or semasb e snore seme se E EE R EE EENE
153. s that extends the Asn1 Real run time class The Asn Real base class is used for standard ASN 1 REAL specifications or XSD float or double types This class encapsulates the following public member variable public double value The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt REAL XSD Types lt xsd float gt lt xsd double gt Generated Java class public class lt name gt extends AsnlReal public lt name gt super public lt name gt double value_ super value_ This shows the class generated for a simple REAL assignment If a tagged or constrained type is specified specific encode and decode methods will be generated as well REAL Base 10 The ASN 1 Base 10 REAL type is converted to a Java class that extends the Asn Real 0 run time class A base 10 real is specified in ASN 1 using a WITH COMPONENTS clause such as the following REAL WITH COMPONENTS base 10 It is also used for XSD decimal type specifications In this case the real number is stored as a Java character string in the character string base class public String value 34 ASN 1 Type to Java Class Mappings ASN 1 Production lt name gt REAL WITH COMPONENTS base 10 XSD Types lt xsd decimal gt Generated Java class public class lt name gt extends AsnlReall0 public lt name gt super public
154. sample program writer l Generate reader sample program reader Generate code for populating data structures test tocol Data Units PDUs Treat all types as Protocol Data Units PDU s pdu Specify a PDU for the sample programs usepdu Debugging and Event Handlers Generate code to invoke event handler callback functions events Generate pure parser event handler callbacks with no types notypes Add tracing diagnostic messages to code trace Other Options V Automatically create unique names for duplicate items Do not add date stamp to generated files nodatestamp Enter command line options not available in GUI 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 usefu
155. scomeoss 9 XSD Opus Ons soi ter tes Ea tities ey es We eee ios ley os Wd eet 12 Java Code Generation Options sieer teaa aiaa Sette ya E sa sea dentg sak bon daha ceatea peep T A 13 Compilation eors eri o EEEE et ck ves EEE tek sishs A ape EE tee sheds ETE E EEE EES 14 Compiler Configuration Piles vos c3fesecessssovsia sh cossessesesesdseestengsscouss ssseden ops sures dseessendesesvansssedseasy selves 15 Compiler Error Reporting iiie ceenecaececed ta hee ccs be costa ceca es EEEE ERES KE EEEREN E ENE ESEETO EE 19 3 Generated Java Source Code OVErview sss sisis iiipen onsere cet eg es E oE E bea su ben deetases E E see seeasese 20 General Form of a Generated Java Source File 2 0 0 0 0c cece cece n ccc eceeeeeneeeeeeeeeceeeseeeeaeeeaeeeaeeaseeaee 20 Package Specification 25 3 3 consgrveg send ee ProAV Eas sbovsasdecs tan dashees cage cDeanasesouacgpeescaudssyatsusheedavedssbeteageens 21 Class Declaration uiii sions tes e chen E EEEE EE EEE E EEE EAE EEE ENEE iS 21 Tag Constant ssie eno eeta eaea e E E E E TA E E E A a E E a 22 Public Member V artables u iesonen o ar eses rone Te E EE EE EE TEE ETER E noel 22 C nstr ctOrS sf ces ses ioe bd EEr AE E EEE PRESAS EEEE EAN EEES TEES EPOS osssedaneds susie ods vedeendessoseagesesanaehs 22 Decode Method r renan eA inte sds E EEEE EE EEE EE EESK EEE E EEEE REE RE REEE EE 23 Encode Method sranie e uber E E E E EE dace E A bar E R ETA EE 24 Other Methods 225 6 is dese oveg esis la seie hush eectias eset
156. scription shortnames stream None 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 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 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 lt module gt _ lt name gt 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 d
157. se 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 22 Generated Java Source Code Overview 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
158. signature is similar public void decode AsnlPerDecodeBuffer 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 23 Generated Java Source Code Overview Encode Method The generated encode method for BER DER has the following general form public int encode AsniBerEncodeBuffer buffer boolean explicit The Asn BerEncodeBuffer 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 t rue 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 ASNIC exception A complete
159. sociated 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 lt include types TypeName1 TypeName2 TypeName3 gt The following are some examples of configuration specifications lt asnlconfig gt lt storage gt dynamic lt storage gt lt asnlconfig gt 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 lt asnilconfig gt lt module gt lt name gt H323 MESSAGES lt name gt lt sourceFile gt h225 asn lt sourceFile gt lt typePrefix gt H225 lt typePrefix gt lt module gt lt asniconfig gt 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 16 Using the Compiler 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 a
160. ss desks e Sater em age se deistoepucadsoey te led ope NE Nae sesh eeansssatel aber een dss ab sceubesy 62 7 Generated PER Encode Methods ereire ra a hes Geaae h oveea oss E AE peblea cee E E weaee ee aera 64 Generated Java Method Format and Calling Parameters cceceeeeeecceeceeeceeeceeeeneeeaeeea eens eeueees 64 Procedure for Calling Java PER Encode Methods 20 0 0 eeceeeceeeceeeee seca seca cena eeue een eeneeenneeenees 65 R use of Java Encoding OBJGCtS sc 0 ccc sssy ered opt oeess dene gue ppwne ss aa wadgg sel A EE ERSE TESE pS 66 8 Generated PER Decode Methods 4 sviccuceateduesie nabiecgseeuiaey au vontased E R E iv O A SANESE aey 68 Generated Java Method Format and Calling Parameters eee ceeceecceece ence eeceeeeneeca seen eens eeuneees 68 Procedure for Calling Java PER Decode Methods 0 00 0 00 cece ccec cece nec cece cece eene cen eeneeeeeeeeeeeeeeeeeeaees 68 Reuse of Java Decoding ODJeCts ses sis vere ss vee eves seve Ere speek es ep eet EA Sen RNEER EEEN S eA 70 9 Generated XML Methods ese bs cesvuvie e alee des Sen ok sede ee oes aed a E a E aches RRS eee 71 OVERVIEW 55s rceetoun sete a ee dent Maesteg cade seadeu a a ads dane er sheathed ee dueetiehiaee deen der OI 71 Differences between OSys XER and XER BASIC XER ceceeeeeceee cece eeeeeeeeeeeeeeetereeetereeaner 71 BXTENDED XER verneint denen a e e A AR eh naltbcth wanes A E AE gy nateters setae 72 Generated Encode Methods is0t si
161. sumption The first constructor sets the value to a reasonable mid range value The second step is the invocation of the encode method The calling arguments were described earlier As per the Java standard this method must be invoked from within a try catch block to catch the possible Asn Exception and java io IOException which may be thrown Alternatively the method from which the encode method is called can declare that it throws Asn1 Exception and java io IOException leaving it to be dealt with at a higher level Finally close the output stream A complete example showing how to invoke a stream based encode method is as follows Note personnelRecord object was previously populated with data AsnlBerOutputStream out null try Step 1 Create an output stream object This object uses the default size increment for buffer expansion out new AsnlBerOutputStream new FileOutputStream filename Step 2 Invoke th ncode method Note that it must be done from within a try catch block personnelRecord encod out true 58 Generated BER DER CER Encode Methods if trace System out println Encoding was successful System out printin Hex dump of encoded record ncodeBuffer hexDump System out printin Binary dump encodeBuffer binDump catch Exception e System out println e getMessage e printStackTrace return finally
162. t 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 Class Declaration Next comes the class declaration It is of the following form public class lt ProdName gt extends lt BaseClass gt lt ProdName gt is the name of the production in the ASN 1 source file lt BaseClass gt 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 21 Generated Java Source Code Overview is an INTEGER so we can directly extend the Asn1 Integer 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 Asn Integer as in the first case Tag Constant The next item in the generated s
163. t returns a negative status value to indicate an encoding failure For Java errors are reported via the exception mechanism All ASNIC Java exceptions are derived from the Asn Exception base class See the section on exceptions for a complete list and description of the various exceptions that can be thrown 64 Generated PER Encode Methods Procedure for Calling Java PER Encode Methods The Java class variables corresponding to each of the ASN 1 types and method of population are the same as they were in the BER encoding case See the section on BER encoding for instructions on how to populate the variables prior to encoding Once an object s member variables have been populated the object s encode method can be invoked to encode the value The general procedure to do this involves the following three steps 1 Create an encode message buffer object into which the value will be encoded 2 Invoke the encode method 3 Invoke encode message buffer methods to access the encoded message component The first step is the creation of an encode message buffer object For PER encoding this is an object of the AsnIPerEncodeBuffer class The following constructors are available for creating a PER encode buffer object public AsnlPerEncodeBuffer boolean aligned public AsnlPerEncodeBuffer boolean aligned int sizeIncrement The first argument indicates whether PER aligned or unaligned encoding should be done The second form of the c
164. tants public final static lt ClassName gt lt name gt new lt ClassName gt lt InfoObject values gt gt For example consider the following Information Object declaration for the above ATTRIBUTE class name ATTRIBUTE WITH SYNTAX VisibleString TO 4 OQ aly gy 90 Table Constraint Processing This would result in the following Java constant being generated public static final ATTRIBUTE name new ATTRIBUTE new AsniVisibleString new AsnlObjectIdentifier new int 0 1 1 NOTE The following new Type Assignment is created for each TypeField s type definition if the type is one of the following ASN 1 built in types Sequence Set SequenceOf SetOf Choice Constrained Type Enumerated Type NamedInteger Type NamedBitList Type ParameterizedType _ lt ObjectName gt _ lt FieldName gt lt Type gt Here ObjectName is replaced with name of the Object Assignment If Object is defined in ObjectSet then ObjectName is replaced with the name of the ObjectSet Assignment FieldName is replaced with name of this type field Type is the type definition in Object s typefield This type is used as Defined Type in the information object definition for type field It is also useful for the user to generate value for related OpenType definition in table constraint Information Object Set NOTE Information Object Set code generation is only done when the tables option is selected
165. te a variable of the type to be used as the argument to the invoke type 2 Assign it to the argument member variable in the structure above 3 Populate the remaining Invoke type fields 4 Encode the Invoke type to produce the final message Note that in this case the intermediate type does not need to be manually encoded by the user The generated encoder has logic built in to encode the complete message using the information in the generated tables Additional Code Generated for the tables Option Following additional code is generated for type definition when the tables command line option is used The code generated to support table constraints is intended for use only in compiler generated code Therefore it is not necessary for the average user to understand the mappings in order to use the product The information presented here is informative only to provide a better understanding of how the compiler handles table constraints Additional equals method will be generated for Sequence Set Sequence Of Set Of or Choice types if required for table constraint processing This method will be an implementation of Asn1Type equals virtual method These methods are used by the generated code to verify that data in a generated structure to be encoded or data that has just been decoded matches the table constraint values An additional table constraint check method is also generated for each type that contains table constraints These funct
166. th ade sudet a a Wats E E E E A EEE 73 Generated Java Method Format and Calling Parameters 0 cceceee cece ence cee ce een een eeneeeeeeeees 74 Procedure for Calling Java XER Encode Methods 1 00 0 00 ccc ceseceecc ence ence eeceeeeeeeeaesea essa sean eeaes 74 Generated Decode Method Sir nissene obey sus age nbsegsingh ceauseuvess EE sedge yveee wade EEEE 78 10 Generated MDER Encode Methods s dirana cde rctncd g hice fea Sosa ete UU SOE a EE RAE EEOSE evens 81 Generated Method Format and Calling Parameters cece cece cece cece cn eece cece een eeneceneeeeeeeeeeeeeeeeeeaees 81 Populating Generated Variables for Encoding o cece cece cece eee cece eee ce cena cena eeneeeneeeeeeeeeeeeeeeeeaees 81 Procedure for Calling MDER Encode Methods 2 0 0 0 00 ccecceecceee cece cece cece ne cene cen eeeeeeeeeeeeeeeeeaeeeaeeeaes 82 Reuse of Java Encoding ODISCts errori ear cauiae deere tn ET E E S E TE aa EN 83 iv ASNIC 11 Generated MDER Decode Methods 20 00 norse p eana a Ea aE Ea eneon Ee 85 Generated Method Format and Calling Parameters 2 0 0 0 cece cece nec ce cece cece cence ee eeneeeeeeeeeeeeeeeeeeaees 85 Procedure for Calling Java MDER Decode Methods 0 cece cece ence ence eeeeeeceeeeaeeea esau eeneeeaeeees 85 Reuse of Java Decoding Objects sosionomer eeni eeii a pE EN EEEN Ea ea 86 12 Table Constraint Processi sosina hres Teese Sates E A OENE E R de Seanee yy teecs dunetseepet
167. thods may be generated using the ASN1C compiler e Memory buffer based definite length backward encoders e Stream based indefinite length forward encoders For DER Distinguished Encoding Rules only the first option is available because a requirement of DER is that all lengths must be in definite form For CER Canonical Encoding Rules only the second option is available because all constructed element lengths must be in indefinite length form Each of these methods are described in the following sections Memory buffer Based Definite Length Encoders For each ASN 1 production defined in an ASN 1 source file a Java encode method may be generated This function will convert a populated variable of the given type into an encoded ASN 1 message An encode method is only generated if it is required to alter the encoding of the base class method The Java model is built on inheritance from a set of common run time base classes These run time classes contain default implementations of encode decode methods that handle the encoding decoding of the basic types These default implementations include support for adding the universal tags associated with the types as defined in the X 680 standard So for simple assignments the generation of an encode method is not necessary For example the following production will not result in the generation of an encode method X INTEGER In this case the generated Java class extends the AsnJ Inte
168. tible 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 noencode None None This option suppresses the generation of decode functions 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 Using the Compiler Option Argument Description 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 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 lt directory gt This op
169. ting 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 Using the Compiler Common Code Generation Options Language Options Function Options _ Utility Options Input File Type Modern ASN 1 1997 based on X 680 standard Legacy ASN 1 based on obsolete X 208 standard with ROSE or SNMP macros Schema XSD E Lax Syntax Check Additional Translations 7 Generate equivalent XML schema XSD file Generate ASN 1 file based o
170. tion causes a component of a sequence to be encoded as an XML attribute e BASE64 This instruction causes octet strings to be encoded in a base64 representation rather than a hexadecimal one Limitations The following are limitations related to EXTENDED XER e For BASE64 ASNIC only supports BASE64 on octet strings Using BASE64 with octet stings having contents constraints open types or restricted character strings is not supported 72 Generated XML Methods e For encoder s options ASN1C decoders do not support the following encoder s options allowed by EXTENDED XER e encoding named bits as empty elements e encoding named numbers as empty elements e Enforcement of Encoding Instruction Restrictions ASN1C does not check that you are using encoding instructions properly Misapplication of encoding instructions has undefined results For example X 693 does not generally allow ATTRIBUTE to be applied to a sequence type there are a few cases where it can be such an application produces malformed XML In particular when applying ATTRIBUTE to a restricted character string type the type should be restricted to exclude the control characters listed in X 680 15 15 5 since these control characters are encoded as empty elements Another solution would be to use ATTRIBUTE and BASE64 together except that ASNIC does not currently support BASE64 for restricted character strings ASN1C will not enforce this rule
171. tion is used to specify the name of a directory to which all of the generated files will be written pdu lt typeName gt 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 lt typeName gt 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 lt packageName gt 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 lt prefixName gt This is a Java option for adding a prefix in front of the assigned Java package name By default 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 Using the Compiler Option Argument De
172. tion used in the ASN 1 definition above does not represent the ASN 1 extensibility notation It is used to show a continuation of the sequence elements 2 The lt typel gt lt type2 gt etc items denote the equivalent Java types generated from the ASN 1 lt element typel gt lt element type2 gt etc definitions 3 The public and private methods that are generated are shown without arguments or function bodies for brevity The compiler first generates a public member variable for each of the elements defined in the SEQUENCE The decision was made to make these variables public to make them easier to populate for encoding The alternative was to use protected or private variables with get set methods for setting or examining the values It was felt that this approach would be too cumbersome for setting values in deeply nested constructed types A default constructor is then generated followed by overloaded constructors for setting the element values The first form is simply a direct mapping of each of the element types to a constructor argument The second form only contains arguments for the required types in the SEQUENCE i e OPTIONAL and DEFAULT elements are omitted The third form uses the base type of each of the elements as the type for each argument This makes it possible to construct a SEQUENCE or SET using literal variables instead of always having to create an object Finally another variant of this constructor with primitive typ
173. to accommodate these types of applications the ASN1C compiler allows an integer to be declared a big integer via a configuration file variable the lt isBigInteger gt 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 Asn BigInteger class instead of the AsnI Integer class The Asn1 BigInteger 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 lt production gt lt name gt SecurityKeyType lt name gt lt isBigInteger gt lt production gt This will cause the compiler to generate the following class header class SecurityKeyType extends AsnlBigInteger The value field is populated by creating a Java BigInteger object and either passing it in through the constructor or using it to directly populate the public member variable named value declared in the base class 28 ASN 1 Type to Java Class Mappings BIT STRING The ASN 1 BIT STRING type is converted to a Java class that extends the Asn BitString run time class This base class encapsulates the following two p
174. ublic member variables public int numbits public byte value These describe the bit string to be encoded or decoded The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt BIT STRING Generated Java class public class lt name gt extends AsnlBitString public lt name gt super public lt name gt int numbits_ byte data super numbits_ data public lt name gt boolean bitValues super bitValues public lt name gt String value_ throws AsnlValueParseException super value_ This shows the class generated for a simple BIT STRING assignment If a tagged or constrained type is specified specific encode and decode methods will be generated as well The constructors generated for this type provide additional options for populating the member variables in the base class In addition to passing the string using the numbits and data arguments to specify a bit string in native format the string can be specified as an array of boolean values or as a string The string form expects the string to be passed in the ASN 1 value notation format for either a binary string i e xxxx B or a hexadecimal string i e xxxx H Named Bits In the ASN 1 standard it is possible to define an enumerated bit string that specifies named constants for different bit positions ASNIC provides support for this type of construct by generating symbolic
175. using the required lt name gt lt name gt tag pair or by specifying the name as an attribute for example lt production name MyProd gt 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 lt typePrefix gt 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 lt name gt value lt name gt 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 lt name gt H323 MESSAGES lt name gt 2 Flag variables that turn some attribute on or off would be specified using a single lt name gt entry For example to specify a given production is a PDU the following would be specified in a production section lt isPDU gt 3 An attribute list can be as
176. utStream class The following constructors are available for creating an XER encode buffer object public AsnlXerOutputStream OutputStream os public AsnlXerOutputStream OutputStream os boolean canonical int bufSize The first constructor creates a buffered XER output stream with default size of an internal buffer Canonical XER is set to false The other form of the constructor allows these variables to be changed Canonical XER specifies that the canonical form of XER encoding CXER as specified in X 693 should be used The buffer size argument specifies the size of the internal buffer of the stream Larger buffer sizes typically provide better performance at the expense of increased memory consumption Similar classes exist for XML encode buffer and streams public AsnlXmlEncodeBuffer public AsnlXmlEncodeBuffer public AsnilXmlOutputStream public AsnlXmlOutputStream int sizeIncrement OutputStream os OutputStream os int bufSize aana asa The main difference is the XML classes to not have a canonical XML option therefore there is not cxer or canonical boolean argument The second step is the invocation of the encode methods The calling arguments were described earlier As per the Java standard this method must be invoked from within a try catch block to catch the possible Asn Exception or java io IOException that may be thrown Alternatively the method from which the encode method is called can declare that it t
177. value For integer and boolean default values the compiler automatically generates code to handle this requirement based on the value in the structure For other values the default value is handled the same as an optional element i e a null object reference indicates that nothing should be transmitted The programmer must set the element object reference to null on the encode side to specify default value selected If this is done a value is not encoded into the message On the decode side the developer must test for a null object reference If this is the case the default value specified in the ASN 1 specification is used Extension Elements If the SEQUENCE type contains an open extension field i e a at the end of the specification or a in the middle a special element will be inserted to capture encoded extension elements for inclusion in the final encoded message This element will be of type ASN OpenExt and have the name extElem1 This field will contain the complete encoding of any extension elements that may have been present in a message when it is decoded On subsequent encode of the type the extension fields will be copied into the new message If the SEQUENCE type contains an extension marker and extension elements then the open extension type field will not be added Instead the actual extension elements will be present These elements will be treated as optional elements whether they were declared that way or not
178. vents trace These are not supported with CLDC 1 1 e Your client code may use either one of two approaches for referring to classes such as ArrayList which are not present in CLDC 1 1 1 explicitly import objsys asn1j runtime ArrayList Your code will only be compatible with our Java ME support jar 2 import java util and objsys asn1j runtime You code may be used in Java SE or Java ME environment You must make sure that only one class named ArrayList is available on your classpath when compiling If compiling for Java SE do not include the ASN1C Java ME runtime JAR If compiling for Java ME use the CLDC 1 1 JAR from the Java ME SDK in your bootclasspath and include the ASNIC Java ME runtime JAR in your classpath e Asn1BigInteger and Asn BigDecimal are not supported e Using the same generated code on both Java SE and Java ME CLDC 1 1 is not supported Compile your ASN 1 specification once for Java SE and once for Java ME e Note that we have not tested using Java ME Connected Device Configuration CDC rather than CLDC Android ASNIC supports the Android platform The ASNIC runtime must be deployed on Android just as it must be deployed in anormal JSE environment However the runtime s Java bytecode must first be converted into Android Dalvik VM bytecode The easiest method is to use the Android ADT Eclipse Plug in and reference the ASN1C Java runtime in the same way as you would for a normal Java application The Android
179. void encode AsnlXerEncoder buffer String elemName throws AsnlException java io IOException The signature for a Java XML encode method is similar public void encode AsnlXmlEncoder buffer String elemName throws AsnlException java io IOException The buffer argument is a reference to an Asn XerEncoder or Asn XmlEncoder derived object that describes the buffer or output stream into which a message is to be encoded Asn XerEncoder is a base interface for the Asn1XerEncodeBuffer and Asn1XerOutputStream classes Similarly Asn XmlEncoder is an interface to a pure XML version of these base classes There is no difference which encode method is used output stream or message buffer The generated logic is the same the difference is only in the first parameter of the encode method This must be created and initialized before calling any encode method See the description of this class in the Java Run Time Classes section for details on how this class is used The elemName argument is a reference to a string containing the element name text This text is used to form the standard XML angle bracketed wrapper that is applied to each element in a message Note the name passed must not contain the angle brackets i e the lt gt characters These will be added by the encode method The elemName can be passed in different ways to control how the name is applied The normal way is to pass a name that is applied as the element name of the
180. witch 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_ lt element gt Public set_ lt element gt 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 24 Generated Java Source Code Overview public class SaxHandler extends AsnlXerSaxHandler AsnlXerSaxHandler mElemSaxHandler StringBuffer mCurrElemValue SaxHandler lt code gt public void startElement String namespaceURI String localName String qName Attributes atts throws SAXException lt code gt public void characters char ch int start int length throws SAXException lt code gt public void endElement String namespaceURI String localName String qName throws SAXException lt code gt This is an implementation of a standard SAX content handler c
181. with other ASN 1 productions defined within the specification An example of the savings of this optimization can be found in H 225 The above element reference is repeated 25 different times in different places The result is the generation of one new temporary type that is referenced in 25 different places Without this optimization 25 unique types with the same definition would have been generated SET OF The ASN 1 SET OF type is converted into a Java class that is identical to that for SEQUENCE OF as described in the previous section CHOICE The ASN 1 CHOICE type is converted to a Java class that extends the Asn Choice run time base class This base class contains protected member variables to hold the choice element object and a selector value to specify which item in the CHOICE was chosen Methods are generated to get and set the base class members The following shows the basic mapping from ASN 1 type to Java class definition ASN 1 Production lt name gt CHOICE lt elementl name gt lt elementl type gt 41 ASN 1 Type to Java Class Mappings lt element2 name gt lt element2 type gt XSD Types lt xsd choice gt lt xsd union gt Generated Java class public class lt name gt extends AsnlChoice public final static byte _ lt ELEMENT1 NAME gt public final static byte _ lt ELEMENT2 NAME public lt name gt super public String getElemNam
182. ype END In this definition an error is assigned an identifying number as well as on optional parameter type to hold parameters associated with the error An example of a reference to this MACRO for the authenticationFailure error in the login operation defined earlier would be as follows applicationError ERROR PARAMETER SEQUENCE errorText IA5String y 1 The ASN1C90 compiler will generate a type definition for the error parameter and a value constant for the error value The format of the name of the type generated will be lt name gt _PARAMETER where lt name gt is the ERROR name 114 ROSE and SNMP Macro Support applicationError in this case with the first letter set to uppercase The name of the value will simply be the ERROR name SNMP OBJECT TYPE The SNMP OBJECT TYPE MACRO is one of several MACROs used in Management Information Base MIB definitions It is the only MACRO of interest to ASNIC because it is the one that specifies the object identifiers and data that are contained in the MIB The version of the MACRO currently supported by this version of ASNIC can be found in the SMI Version 2 RFC RFC 2578 The compiler generates code for two of the items specified in this MACRO definition 1 The ASN 1 type that is specified using the SYNTAX command and 2 The assigned OBJECT IDENTIFIER value For an example of the generated code we can look at the following definition from the UDP MIB

Generated Java Method Format and Calling Parameters

Contents

Download Pdf Manuals

Related Search

Related Contents