Implementation:Microsoft Onnxruntime OrtJniUtil

Knowledge Sources	Description
Source File	java/src/main/native/OrtJniUtil.c
Repository	Microsoft/onnxruntime

Domains

• JNI Native Bridge
• Type Conversion Utilities
• ORT Value Marshalling

Overview

OrtJniUtil.c is the central JNI utility file for the ONNX Runtime Java binding. It provides type conversion functions between Java and ORT C API enums, error handling via checkOrtStatus and throwOrtException, half-precision floating point conversion, and factory functions that construct Java-side OnnxTensor, OnnxSparseTensor, OnnxSequence, OnnxMap, TensorInfo, MapInfo, and SequenceInfo objects from native ORT values.

Description

Key function groups:

• JNI lifecycle: JNI_OnLoad returns JNI_VERSION_1_6 (Android compatible).
• Enum converters: convertLoggingLevel, convertOptimizationLevel, convertExecutionMode, convertToOrtSparseFormat/convertFromOrtSparseFormat, convertFromCompiledModelCompatibility/convertToCompiledModelCompatibility, convertFromONNXDataFormat/convertToONNXDataFormat (21 tensor element types).
• Type size: onnxTypeSize maps ONNX tensor element types to byte sizes (1/2/4/8/0).
• Tensor info extraction: getTensorTypeShape extracts dimensions, element count, and type from an OrtValue.
• FP16/BF16 conversion: convertHalfToFloat and convertBF16ToFloat for native-side upconversion.
• Value info construction: convertToValueInfo dispatches to convertToTensorInfo, convertToMapInfo, or convertToSequenceInfo based on ONNXType.
• Java object factories: createJavaTensorFromONNX, createJavaSparseTensorFromONNX, createJavaSequenceFromONNX, createJavaMapFromONNX construct Java wrapper objects.
• Array copy: copyPrimitiveArrayToJava handles all primitive types including fp16/bf16 upconversion. copyStringTensorToArray extracts string tensor data.
• Error handling: checkOrtStatus checks OrtStatus, throws OrtException on error, and returns the error code. throwOrtException constructs and throws the Java exception. convertErrorCode maps ORT error codes to ints.
• Safe casting: safecast_size_t_to_jsize and safecast_int64_to_jsize with debug-mode abort on overflow.

Code Reference

Source Location

// File: java/src/main/native/OrtJniUtil.c

Signature

// Enum converters
OrtLoggingLevel convertLoggingLevel(jint level);
GraphOptimizationLevel convertOptimizationLevel(jint level);
ExecutionMode convertExecutionMode(jint mode);
ONNXTensorElementDataType convertToONNXDataFormat(jint type);
jint convertFromONNXDataFormat(ONNXTensorElementDataType type);
OrtSparseFormat convertToOrtSparseFormat(jint format);
jint convertFromOrtSparseFormat(OrtSparseFormat format);
size_t onnxTypeSize(ONNXTensorElementDataType type);

// Tensor type/shape extraction
OrtErrorCode getTensorTypeShape(JNIEnv*, JavaTensorTypeShape*, const OrtApi*, const OrtValue*);

// FP16/BF16 conversion
jfloat convertHalfToFloat(const uint16_t half);
jfloat convertBF16ToFloat(const uint16_t bf16);

// Java object factories
jobject convertOrtValueToONNXValue(JNIEnv*, const OrtApi*, OrtAllocator*, OrtValue*);
jobject createJavaTensorFromONNX(JNIEnv*, const OrtApi*, OrtAllocator*, OrtValue*);
jobject createJavaSparseTensorFromONNX(JNIEnv*, const OrtApi*, OrtAllocator*, OrtValue*);

// Error handling
OrtErrorCode checkOrtStatus(JNIEnv*, const OrtApi*, OrtStatus*);
jint throwOrtException(JNIEnv*, int, const char*);

Import

#include "OrtJniUtil.h"

I/O Contract

Inputs

Name	Type	Description
apiHandle	const OrtApi*	Pointer to the ORT C API struct
value	const OrtValue*	Native ORT tensor/map/sequence value
status	OrtStatus*	ORT operation status (NULL on success)

Outputs

Name	Type	Description
Java object	jobject	OnnxTensor, OnnxSparseTensor, OnnxMap, or OnnxSequence
OrtErrorCode	OrtErrorCode	Error code (ORT_OK on success)

Usage Examples

// Inside a JNI function, convert an OrtValue to a Java OnnxValue
jobject javaValue = convertOrtValueToONNXValue(jniEnv, api, allocator, ortValue);
// This dispatches to createJavaTensorFromONNX, createJavaSequenceFromONNX,
// createJavaMapFromONNX, or createJavaSparseTensorFromONNX based on type.

// Check a status and throw OrtException if non-OK
OrtErrorCode code = checkOrtStatus(jniEnv, api, api->SomeOperation(args));
if (code != ORT_OK) {
    return NULL;  // Exception already thrown
}

Related Pages

• ai_onnxruntime_OnnxTensor.c - Uses OrtJniUtil for tensor operations
• ai_onnxruntime_OrtSession.c - Uses OrtJniUtil for session operations
• OrtException.java - Java exception thrown by throwOrtException
• TensorInfo.java - Constructed by convertToTensorInfo