ASN.1 J275 + SEMI Extensions PER-XER Codec

The PER-XER Codec is an open source library which wraps the C code generated by asn1c in a JNI wrapper.

Table of Contents

I. Release Notes

II. Documentation

III. Getting Started

IV. Code Generation

V. Building the Library (Combined)

VI. Building the Library (Standalone Native)

VII. Usage

---

I. Release Notes

II. Documentation

This project produces two artifacts: A native-code Shared Object library, and a JAR wrapper around that library.

III. Getting Started

The following instructions describe the proceedure to fetch, build, and run the application

Prerequisites

• git
• make
• java 1.8
• maven
• asn1c (See below)

---

Obtain the Source Code

Step 1 - Clone public repository

Clone the source code from the GitHub repository using Git command:

git clone --recurse-submodules https://github.com/usdot-jpo-sdcsdw/per-xer-codec.git

IV. Code Generation

Step 1: Create the various empty directories that git won't track

Navigate to the codegen directory and run the appropriate make rule

cd asn1-codegen
make directories

Step 2: Add the necessary ASN 1 files

cp ... src/asn1/ 

Step 3: Generate the ASN.1 C code

Still in the codegen directory, run the full make, and then install

make
make install

This will:

• Build the asn1c compiler
• Install it into asn1-codegen/install/asn1c
• Generate the c code using the ASN.1 files provided
• Move them to the native/src/main/c/asn1 directory

V. Building the Library (Combined)

This step is for building the library as a complete maven project, which will yield both the JNI Jar, and a native shared object library for it to use.

Step 1: Follow the instructions in IV. Code Generation

Step 2: Build using maven

From the root directory, and run the maven install goal

mvn install

The maven configuration is set up to detect what OS you are building on, and will install the appropriate native library. Cross compiling is not currently supported. OSX and Linux are currently the only supported OS's.

VI. Building the Library (Standalone Native)

This step is for building the native shared library by itself, separate from the JNI wrapper

Step 1: Follow the instructions in IV. Code Generation

Step 2: Build using make

From the native directory, run make

cd native
make

This makefile supports building the Linux Shared object on OSX, using a docker container, and will detect this automatically

This will: Produce a docker image capable of building the Linux shared object library Produce a container of that image, and build the shared object in it Copy the built shared object out of the container Delete the container

VII. Usage

Intended Usage

The primary way to use this module is to include the PerXerCodec class, and use its perToXer and xerToPer methods. These methods require 3 things: A PerData format, a XerData Format, and an Asn1Type. Asn1Types can be accessed as static members of PerXerCodec (e.g. ServiceRequestType). The PerData can be any object that implements the PerData interface, Likewise for XerData. If the type of data is unknown, the guessPerToXer and guessXerToPer take multiple possible data types and will try each.

Maven Dependency

Maven projects which wish to use the codec must declare two dependencies, the java wrapper (per-xer-codec-java), and the appropriate shared object (per-xer-codec-native-osx|linux).

If you wish to run unit tests in your project which depend on the codec, you will need to ensure the native shared object exists at test run time, and specify the java.library.path to your unit test runner.

Deploying

Step 1: Place the jar file generated by the build process on the classpath

Step 2: Place the generated shared object file on the java native library path This is set using the java.library.path java system property, i.e. using the -Djava.library.path=... command line argument. If not provided, this property usually defaults to the system library path.