Ukraine We stand with Ukraine

TOP
home | What's New | Installing the Tools | Getting Started | Knowledge Center | Standards Conformance

Getting Started

Applies to: ASN.1/Java v8.7

Contents

Quick Start

Here are a few quick steps to get you started:

  1. Install the OSS ASN.1 Tools on your platform.
  2. Compile your ASN.1 specifications. Use either ASN.1 Studio or the ASN.1/Java command line compiler. This will generate Java classes representing ASN.1 types. Include these classes into your application.
  3. Launch your Java development environment, instantiate the Java class that represents an application message (PDU), and fill the object with data.
  4. Instantiate the Coder object and invoke its methods to encode/decode your application messages.
  5. Build your application: compile your application code along with the ASN.1/Java compiler-generated classes.
  6. Run and test your application.

The samples/standards directory contains sample programs that demonstrate support for various industry standards using ASN.1.

Compile and Run Your ASN.1 Schemas Manually

  1. Choose a project name.
    This is the name of the directory where the OSS ASN.1/Java compiler generates the Java source code for your ASN.1 schema. This is also the name of the top-level Java package for the generated Java classes. By default, the project package name is the same as the name of the last .asn file in the input. To change the name, use the -output packagename compiler option, for example, -output com.mycompany.myproject.
  2. Compile your ASN.1 schema with the OSS ASN.1/Java compiler.
    You may need to specify the encoding rules option if rules other than BER are needed. By default, the compile generates support for BER encoding rules only.
  3. Use the -test compiler option to create a Java test class in Test.java.
    This class defines the main() method and can be run as a Java application. The application encodes and then decodes values found in an ASN.1 schema and reports on success or failure of the encode/decode operations for all selected encoding rules. Following are compiler command-line examples: 
    asn1pjav your_source.asn
    asn1pjav your_source.asn -ber -per -output project_name
    asn1pjav your_source.asn -ber -xer -test
  4. Change to your project directory, and run the .bat batch file.
    You may need to pass the name of your Java compiler (by default javac is used) as the first parameter to the .bat file. Before running the script, ensure that your CLASSPATH is set so that your project directory can be found by the Java compiler 
    your_project.bat
    If you compiled with the -test option, then you can run the encoder/decoder tests with the Test class. 
    java your_project.Test
  5. Run javadoc on your project.
    This generates HTML documentation that allows you to view the classes and methods, the API, of your project.

NOTE: Always run javadoc with the -public option. Only public methods and constructors in the generated Java code are available for your use.

  1. Choose a project name.
    This is the name of the directory where the OSS ASN.1/Java compiler generates the Java source code. This is also the name of the top-level Java package for the generated Java classes. By default, the project package name is the same as the name of the last .asn file in the input. To change the name, use the -output packagename compiler option, for example, -output com.mycompany.myproject.
  2. Compile your ASN.1 specification with the OSS ASN.1/Java compiler.
    You may need to specify the encoding rules option if rules other than BER are needed. By default, the compile generates support for BER encoding rules only.
  3. Use the -test compiler option to create a Java test class in Test.java.
    This class defines the main() method and can be run as a Java application. The application encodes and then decodes values found in an ASN.1 specification and reports on success or failure of the encode/decode operations for all selected encoding rules. Following are compiler command line examples: 
    asn1pjav your_source.asn
    asn1pjav your_source.asn -ber -per -output project_name
    asn1pjav your_source.asn -ber -xer -test
  4. Change to your project directory, and run the .sh shell script file.
    You may need to pass the name of your Java compiler (by default javac is used) as the first parameter to the .sh file. Before running the script you need to ensure that your CLASSPATH is set so that your project directory can be found by the Java compiler. 
    sh your_project.sh
    If you compiled with the -test option, you can run the encoder/decoder tests with the Test class. 
    java your_project.Test
  5. Run javadoc on your project.
    This generates HTML documentation that allows you to view the classes and methods, the API, of your project.

NOTE: Always run javadoc with the -public option. Only public methods and constructors in the generated Java code are available for your use.

Use ASN.1 Studio to Compile and Run Your ASN.1 Schemas

  1. Open ASN.1 Studio, click File > New > New Project, or the corresponding button on the ASN.1 Studio toolbar. Choose the ASN.1/Java project radio button on the first page of the New Project Wizard dialog and follow the dialog instructions to select the name, location, encoding rules, and ASN.1 files, and then click Finish.
  2. Click Project > Settings, or the corresponding toolbar button, and select the command-line options to be used to invoke asn1pjav in the Project Settings dialog. Each control in the dialog corresponds to an ASN.1 compiler option or to a runtime flag. All controls have tooltips that explain the purpose of each setting.
  3. To build your application, export the project to a batch file that will build the Java application: right-click the project name in the Projects window and select Export Project To... from the context menu, then select Batch file that will build Java application in the Project Export Wizard dialog. Follow the dialog steps and click Finish. Once the project is exported, a message appears in the Diagnostic window that contains two hyperlinks: the first one opens the exported batch file in the Text Editor; the second one launches the batch file.
  4. Click the second hyperlink to Java compile and build your application using the generated classes.
  5. Run the application: 
    java <Class_Name>
  1. Open ASN.1 Studio, click File > New > New Project, or the corresponding button on the ASN.1 Studio toolbar. Choose the ASN.1/Java project radio button on the first page of the New Project Wizard dialog and follow the dialog instructions to select the name, location, encoding rules, and ASN.1 files, and then click Finish.
  2. Click Project > Settings, or the corresponding toolbar button, and select the command-line options to be used to invoke asn1pjav in the Project Settings dialog. Each control in the dialog corresponds to an ASN.1 compiler option or to a runtime flag. All controls have tooltips that explain the purpose of each setting.
  3. To build your application, export the project to a shell script that will build the Java application: right-click the project name in the Projects window and select Export Project To... from the context menu, then select Shell script that will build Java application in the Project Export Wizard dialog. Follow the dialog steps and click Finish. Once the project is exported, a message appears in the Diagnostic window that contains two hyperlinks: the first one opens the exported shell script in the Text Editor; the second one launches the shell script.
  4. Click the second hyperlink to Java compile and build your application using the generated classes.
  5. Run the application: 
    java <Class_Name>

Samples

The OSS ASN.1 Tools for Java comes with numerous samples that illustrate how your application can use the classes generated by the OSS ASN.1/Java compiler.

Each sample program owns a subdirectory in the samples directory. Each subdirectory contains the gui subdirectory, which contains an ASN.1 Studio project for the sample. For example, the baseball sample is located in the samples\basic\baseball directory.

Each sample includes the following files and directory:

  • README.TXT
  • run.bat, a batch file that runs the sample
  • sample.out, which contains the expected output from running the sample
  • gui, a subdirectory that contains an ASN.1 Studio project file for the sample

For details about ASN.1 Studio, see ASN.1 Studio Help.

Each of the samples can be run individually or you can run all the samples in one step. To run the samples one by one, follow the same procedure used to run the baseball sample: change to a sample directory and invoke the run.bat file, which will run the sample.

The run.bat file will create a compile.log file, which contains messages from the ASN.1/Java compiler. This file is useful if you have problems when running the sample. When you are finished running the sample, you can remove all the intermediate files and return the sample directory to its previous clean state by invoking run.bat with the clean parameter:

run clean

To run all the samples in one step, change to the samples directory and invoke the runall.bat batch file:

runall

The runall.bat file will execute all the run.bat files in the samples\basic and samples\advanced subdirectories, creating a run.log file in each subdirectory. Change to a sample directory and examine the run.log file to see the result of running the sample. The cleanup.bat file in the samples directory will invoke all the run.bat files with the clean parameter.

For more information, see the README.TXT file in the samples directory.

The OSS ASN.1 Tools for Java comes with numerous samples that illustrate how your application can use the classes generated by the OSS ASN.1/Java compiler.

Each sample program owns a subdirectory in the samples directory. Each subdirectory contains the gui subdirectory, which contains an ASN.1 Studio project for the sample. For example, the baseball sample is located in the samples/basic/baseball directory.

Each sample includes the following files and directory:

  • README.TXT
  • run.sh, a shell script that runs the sample
  • sample.out, which contains the expected output from running the sample
  • gui, a subdirectory that contains an ASN.1 Studio project file for the sample

For details about ASN.1 Studio, see ASN.1 Studio Help.

Before running the samples, we recommend that you create your own copy of the samples directory. Each of the samples can be run individually or you can run all the samples in one step. To run the samples one by one, follow the same procedure used to run the baseball sample: change to a sample directory and invoke the run.sh shell script, which will run the sample. It's a good idea to capture the sample output in a file, so it can be examined later on.

sh run.sh | tee run.log

The run.sh script will create a compile.log file, which contains messages from the ASN.1/Java compiler. This file is useful if you have problems when running the sample. When you are finished running the sample, you can remove all the intermediate files and return the sample directory to its previous clean state by invoking run.sh with the cleanup parameter:

sh run.sh cleanup

To run all the samples in one step, change to the samples directory and invoke the runall.sh script:

sh runall.sh

The runall.sh script will execute all the run.sh scripts in the samples/basic and samples/advanced subdirectories, creating a run.log file in each subdirectory. Change to a sample directory and examine the run.log file to see the result of running the sample. The cleanup.sh script in the samples directory will invoke all the run.sh scripts with the cleanup parameter.

For more information, see the README.TXT file in the samples directory.

Compile and Run the Baseball Sample

To check that your installation is complete, compile and run the baseball sample.

The samples for Windows 8 and later platforms are installed in the folders pointed to by the ALLUSERSPROFILE environment variable that, by default, is set to C:\ProgramData. Using this default setting, the samples are installed in the following folder:

C:\ProgramData\OSS Nokalva\asn1pjav\<platform name>\<version number>\samples

If you use the OSS command prompt window, you do not need to set the environment variables before running the samples. All environment variables are automatically set as needed in the OSS command prompt window. Otherwise, before running any samples, make sure you have set up the environment variables as required by the OSS ASN.1 Tools for Java installation.

To run the baseball sample:

  1. Change to the samples\basic\baseball directory. Review the README.TXT file, which contains a description of the sample. 
    C:\> cd \ProgramData\OSS Nokalva\asn1pjav\<platform name>\<version number>\samples\basic\baseball
  2. Invoke the run.bat batch file, which will ASN.1 compile, Java compile, and run the baseball sample. 
    C:\ProgramData\OSS Nokalva\asn1pjav\<platform name>\<version number>\samples\basic\baseball> run
  3. Review the output printed by the sample in the command prompt window. If your environment is set up correctly, you will get the same output as the one in sample.out.

If you experience problems when running the baseball sample:

  1. Check that the environment variables are properly set.
  2. Review the compile.log file for possible ASN.1 compiler errors.
  3. Try to run the baseball sample manually as described in the next section: Compile and Run the Baseball Sample Manually.

To check that your installation is complete, compile and run the baseball sample.

Before running any samples, make sure you have set the environment variables as required by the OSS ASN.1 Tools for Java installation. You may also need to copy the samples directory into your home directory if you do not have write permission for the Tools installation directory. We recommend that you create a copy even if the Tools installation directory is writable by you. To create a copy, change to your home directory or other directory that is writable by you and issue the following command:

(cd $OSS_ASN1_JAVA; tar -cf - samples) | tar -xf -

Now you are ready to run your local copy of the samples. The samples directory below refers to either your local copy or the installation samples directory, if you chose not to create a local copy.

To run the baseball sample:

  1. Change to the samples/basic/baseball directory. Review the README.TXT file, which contains a description of the sample. 
    C:\> cd /samples/basic/baseball
  2. Invoke the run.sh shell script, which will ASN.1 compile, Java compile, and run the baseball sample. 
    sh run.sh | tee run.log
  3. The above command runs the sample and captures standard output into the run.log file. The expected output from the sample is in the sample.out file. Compare the files to see if the actual output is the same, as expected. If your setup is correct then the diff command should produce no output. 
    diff run.log sample.out

If you experience problems when running the baseball sample:

  1. Check that the environment variables are properly set.
  2. Review the compile.log file for possible ASN.1 compiler errors.
  3. Try to run the baseball sample manually as described in the next section: Compile and Run the Baseball Sample Manually.

Compile and Run the Baseball Sample Manually

Running the baseball sample manually can help you solve setup problems. Also, it gives you an idea of how to compile and run your own application. In general, the following steps are required for any ASN.1 Tools for Java application:

  1. Compile the ASN.1 schema file using asn1pjav, the ASN.1/Java compiler. This will produce a set of Java classes (known as the ASN.1 project) that correspond to the ASN.1 types in the schema.
  2. Java compile the classes generated in step 1.
  3. Java compile an application program that uses the generated classes.
  4. Run the application.

The baseball sample compiles and runs Tbcas.java, the simple Java application program that uses the baseball.asn ASN.1 schema. To manually run the above steps for the baseball sample, do the following:

  1. Change to the samples\basic\baseball directory. 
    C:\> cd \ProgramData\OSS Nokalva\asn1pjav\<platform name>\<version number>\samples\basic\baseball
  2. Invoke asn1pjav to ASN.1 compile the baseball.asn schema. 
    asn1pjav baseball.asn
  3. The above command creates the baseball ASN.1 project directory and populates it with generated .java files. It also creates the baseball.bat batch file in the project directory, which is used to Java compile the generated files. The batch file assumes that the parent of the project directory is in your CLASSPATH, so you need to adjust the CLASSPATH accordingly before invoking the batch file. When you run the sample using run.bat this is done for you automatically. Issue the following command: 
    set CLASSPATH=%OSS_ASN1_JAVA%\samples\basic\baseball;%CLASSPATH%
  4. Change to the baseball project directory created by the ASN.1/Java Compiler and invoke the baseball.bat file to Java compile the generated classes. 
    cd baseball
baseball javac
  5. Change back to the parent directory and Java compile the Tbcas.java sample application program. 
    cd ..
javac Tbcas.java
  6. Run the program. 
    java Tbcas

At this point, you will see trace information printed out by the OSS ASN.1/Java runtime.

Running the baseball sample manually can help you solve setup problems. Also, it gives you an idea of how to compile and run your own application. In general, the following steps are required for any ASN.1 Tools for Java application:

  1. Compile the ASN.1 schema file using asn1pjav, the ASN.1/Java compiler. This will produce a set of Java classes (known as the ASN.1 project) that correspond to the ASN.1 types in the schema.
  2. Java compile the classes generated in step 1.
  3. Java compile an application program that uses the generated classes.
  4. Run the application.

The baseball sample compiles and runs Tbcas.java, the simple Java application program that uses the baseball.asn ASN.1 schema. To manually run the above steps for the baseball sample, do the following:

  1. Change to the samples/basic/baseball directory. As in the previous section, the samples directory refers either to your local copy or the installation samples directory. 
    cd samples/basic/baseball
  2. Invoke asn1pjav to ASN.1 compile the baseball.asn schema. 
    asn1pjav baseball.asn
  3. The above command creates the baseball ASN.1 project directory and populates it with generated .java files. It also creates the baseball.sh shell script in the project directory, which is used to Java compile the generated files. The script assumes that the parent of the project directory is in your CLASSPATH, so you need to adjust the CLASSPATH accordingly before invoking the script. When you run the sample using run.sh this is done for you automatically. Depending on your shell, issue the following: 
    setenv CLASSPATH $PWD:$CLASSPATH
    for csh, issue: 
    CLASSPATH=$PWD:$CLASSPATH;
    export CLASSPATH for sh or ksh.
  4. Change to the baseball project directory created by the ASN.1/Java Compiler and invoke the baseball.sh shell script to Java compile the generated classes. 
    cd baseball sh
baseball.sh
  5. Change back to the parent directory and Java compile the Tbcas.java sample application program. 
    cd ../
javac Tbcas.java
  6. Run the program. 
    java Tbcas

At this point, you will see trace information printed out by the OSS ASN.1/Java runtime.

Use ASN.1 Studio to Compile and Run the Baseball Sample

ASN.1 Studio simplifies compiling and running the baseball sample. Follow the steps below:

  1. Start ASN.1 Studio.
    From the Windows task bar, click Start and go to the OSS ASN.1 Tools for Java xxx program group and click the ASN.1 Studio shortcut. You can quickly check sample projects without generating Java code from the Welcome page of ASN.1 Studio. Detailed help is available from the Help > Contents menu option in the main window.
  2. Open the Baseball ASN.1/Java project.
    Click File > Open Project in the main menu, or the corresponding tool button on the toolbar, change to the samples\basic\baseball directory in the system Open File dialog, and select Baseball.a1sproj. 
    \ProgramData\OSS Nokalva\asn1pjav\<platform name>\<version number>\samples\basic\baseball\gui
  3. ASN.1 compile the Baseball project.
    Click Project > Compile in the main menu, or the corresponding tool button on the toolbar, to compile the Baseball ASN.1/Java project using asn1pjav, the ASN.1/Java compiler. This will produce a set of Java classes and a batch file in the Generated Files sub-folder under the Baseball node in the Projects window. The result of the ASN.1 compilation is displayed in the Diagnostic window.
  4. Export the project to a batch file that will build the Java application.
    Right-click Tbcas in the Projects window and select Export Project To... in the context menu, and select Batch file that will build Java application in the Project Export Wizard dialog. Follow the steps in the dialog and click Finish. Once the project is exported, a message appears in the Diagnostic window that contains two hyperlinks: the first one opens the exported batch file in the Text Editor; the second one launches the batch file.
  5. Java compile an application program that uses the generated classes.
    Click the second hyperlink to build your application.
  6. Run the application: 
    java Tbcas

At this point, you will see trace information printed out by the OSS ASN.1/Java runtime.

ASN.1 Studio simplifies compiling and running the baseball sample. Follow the steps below:

  1. Start ASN.1 Studio.
    From a shell prompt type the executable name asn1studio (first make sure that the bin directory of the ASN.1 Studio installation is in your PATH). You can quickly check sample projects without generating Java code from the Welcome page of ASN.1 Studio. Detailed help is available from the Help > Contents menu option in the main window.
  2. Open the Baseball ASN.1/Java project.
    Click File > Open Project in the main menu, or the corresponding tool button on the toolbar, change to the samples/basic/baseball directory in the system Open File dialog, and select Baseball.a1sproj. 
    <installation root>/asn1pjav/<platform name>/<version number>/samples/basic/baseball/gui
  3. ASN.1 compile the Baseball project.
    Click Project > Compile in the main menu, or the corresponding tool button on the toolbar, to compile the Baseball ASN.1/Java project using asn1pjav, the ASN.1/Java compiler. This will produce a set of Java classes and a shell script in the Generated Files sub-folder under the Baseball node in the Projects window. The result of the ASN.1 compilation is displayed in the Diagnostic window.
  4. Export the project to a shell script that will build the Java application.
    Right-click Tbcas in the Projects window and select Export Project To... in the context menu, and select Shell script that will build Java application in the Project Export Wizard dialog. Follow the steps in the dialog and click Finish. Once the project is exported, a message appears in the Diagnostic window that contains two hyperlinks: the first one opens the exported shell script in the Text Editor; the second one launches the shell script.
  5. Java compile an application program that uses the generated classes.
    Click the second hyperlink to build your application.
  6. Run the application: 
    java Tbcas

At this point, you will see trace information printed out by the OSS ASN.1/Java runtime..

This documentation applies to the OSS® ASN.1 Tools for Java release 8.7 and later.

Copyright © 2024 OSS Nokalva, Inc. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means electronic, mechanical, photocopying, recording or otherwise, without the prior permission of OSS Nokalva, Inc.
Every distributed copy of the OSS® ASN.1 Tools for Java is associated with a specific license and related unique license number. That license determines, among other things, what functions of the OSS ASN.1 Tools for Java are available to you.