Implementation:Microsoft Onnxruntime OrtSession JNI

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

Domains

• JNI Native Bridge
• Session Management
• Model Inference

Overview

ai_onnxruntime_OrtSession.c is the JNI native implementation file for the OrtSession Java class. It provides native methods for creating inference sessions from file paths, byte arrays, or direct ByteBuffers, querying model input/output names and type information, executing model inference via the run method, profiling, and constructing the Java OnnxModelMetadata object from native metadata.

Description

Key function groups:

• Session creation: Three overloaded createSession methods: (1) from a file path string with platform-specific wide-char handling on Windows; (2) from a direct ByteBuffer with position and size; (3) from a Java byte array. All accept an OrtSessionOptions handle.
• Input/Output counts: getNumInputs and getNumOutputs return the number of model inputs/outputs via SessionGetInputCount/SessionGetOutputCount.
• Name queries: getInputNames and getOutputNames return String[] arrays of input/output names, allocating and freeing each name through the ORT allocator.
• Type info queries: getInputInfo and getOutputInfo return NodeInfo[] arrays. Each entry pairs a name string with a ValueInfo object constructed by convertToValueInfo from OrtJniUtil.
• Inference execution: run accepts input names, input OrtValue handles, output names, optional pre-allocated output handles, and run options. It calls api->Run, then converts output OrtValues to Java OnnxValue objects via convertOrtValueToONNXValue. Returns a boolean array indicating which outputs ORT owns.
• Profiling: getProfilingStartTimeInNs returns the profiling start timestamp. endProfiling returns the profile output file path.
• Metadata construction: constructMetadata extracts producer name, graph name, graph description, domain, description, version, and custom metadata key-value pairs, constructing a Java OnnxModelMetadata object.
• Session cleanup: closeSession releases the native OrtSession.

The file defines class name constants (ORTJNI_StringClassName, ORTJNI_OnnxValueClassName, ORTJNI_NodeInfoClassName, ORTJNI_MetadataClassName) used for JNI class lookups. Memory management in run uses goto-based cleanup to ensure all allocated arrays are freed on both success and failure paths.

Code Reference

Source Location

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

Signature

// Session creation (3 overloads)
JNIEXPORT jlong JNICALL Java_ai_onnxruntime_OrtSession_createSession__JJLjava_lang_String_2J
    (JNIEnv*, jclass, jlong apiHandle, jlong envHandle, jstring modelPath, jlong optsHandle);
JNIEXPORT jlong JNICALL Java_ai_onnxruntime_OrtSession_createSession__JJLjava_nio_ByteBuffer_2IIJ
    (JNIEnv*, jclass, jlong apiHandle, jlong envHandle, jobject buffer, jint bufferPos, jint bufferSize, jlong optsHandle);
JNIEXPORT jlong JNICALL Java_ai_onnxruntime_OrtSession_createSession__JJ_3BJ
    (JNIEnv*, jclass, jlong apiHandle, jlong envHandle, jbyteArray modelArray, jlong optsHandle);

// Input/Output queries
JNIEXPORT jlong JNICALL Java_ai_onnxruntime_OrtSession_getNumInputs(JNIEnv*, jobject, jlong, jlong);
JNIEXPORT jlong JNICALL Java_ai_onnxruntime_OrtSession_getNumOutputs(JNIEnv*, jobject, jlong, jlong);
JNIEXPORT jobjectArray JNICALL Java_ai_onnxruntime_OrtSession_getInputNames(JNIEnv*, jobject, jlong, jlong, jlong);
JNIEXPORT jobjectArray JNICALL Java_ai_onnxruntime_OrtSession_getOutputNames(JNIEnv*, jobject, jlong, jlong, jlong);
JNIEXPORT jobjectArray JNICALL Java_ai_onnxruntime_OrtSession_getInputInfo(JNIEnv*, jobject, jlong, jlong, jlong);
JNIEXPORT jobjectArray JNICALL Java_ai_onnxruntime_OrtSession_getOutputInfo(JNIEnv*, jobject, jlong, jlong, jlong);

// Inference
JNIEXPORT jbooleanArray JNICALL Java_ai_onnxruntime_OrtSession_run
    (JNIEnv*, jobject, jlong apiHandle, jlong sessionHandle, jlong allocatorHandle,
     jobjectArray inputNamesArr, jlongArray tensorArr, jlong numInputs,
     jobjectArray outputNamesArr, jlong numOutputs,
     jobjectArray outputValuesArr, jlongArray outputHandlesArr, jlong runOptionsHandle);

// Profiling
JNIEXPORT jlong JNICALL Java_ai_onnxruntime_OrtSession_getProfilingStartTimeInNs(JNIEnv*, jobject, jlong, jlong);
JNIEXPORT jstring JNICALL Java_ai_onnxruntime_OrtSession_endProfiling(JNIEnv*, jobject, jlong, jlong, jlong);

// Metadata
JNIEXPORT jstring JNICALL Java_ai_onnxruntime_OrtSession_constructMetadata(JNIEnv*, jobject, jlong, jlong, jlong);

// Cleanup
JNIEXPORT void JNICALL Java_ai_onnxruntime_OrtSession_closeSession(JNIEnv*, jobject, jlong, jlong);

Import

#include "OrtJniUtil.h"
#include "ai_onnxruntime_OrtSession.h"

I/O Contract

Inputs

Name	Type	Description
apiHandle	jlong	Pointer to the ORT C API struct
envHandle	jlong	Pointer to the OrtEnv
sessionHandle	jlong	Pointer to the native OrtSession
optsHandle	jlong	Pointer to OrtSessionOptions
allocatorHandle	jlong	Pointer to the ORT allocator
modelPath	jstring	File system path to the ONNX model
buffer	jobject (ByteBuffer)	Direct buffer containing serialized model bytes
modelArray	jbyteArray	Java byte array containing serialized model
inputNamesArr	jobjectArray	String array of input names for inference
tensorArr	jlongArray	Array of native OrtValue handles (inputs)
outputNamesArr	jobjectArray	String array of requested output names
runOptionsHandle	jlong	Pointer to OrtRunOptions (may be NULL)

Outputs

Name	Type	Description
sessionHandle	jlong	Pointer to the newly created OrtSession
inputCount/outputCount	jlong	Number of model inputs or outputs
String[]	jobjectArray	Input/output name arrays
NodeInfo[]	jobjectArray	Input/output type information arrays
boolean[]	jbooleanArray	Per-output flag indicating ORT memory ownership
OnnxModelMetadata	jobject	Java metadata object with producer, graph, domain, version, custom metadata

Usage Examples

// Inside JNI: create a session from a file path
jlong session = Java_ai_onnxruntime_OrtSession_createSession__JJLjava_lang_String_2J(
    jniEnv, cls, apiHandle, envHandle, modelPathStr, sessionOptsHandle);

// Query input names
jobjectArray names = Java_ai_onnxruntime_OrtSession_getInputNames(
    jniEnv, sessionObj, apiHandle, session, allocHandle);

// Run inference
jbooleanArray ownership = Java_ai_onnxruntime_OrtSession_run(
    jniEnv, sessionObj, apiHandle, session, allocHandle,
    inputNames, inputHandles, numInputs,
    outputNames, numOutputs, outputValues, outputHandles, runOptsHandle);

// Close the session
Java_ai_onnxruntime_OrtSession_closeSession(jniEnv, sessionObj, apiHandle, session);

Related Pages

• OrtSession.java - Java-side session class calling these natives
• ai_onnxruntime_OrtSession_SessionOptions.c - SessionOptions JNI implementation
• OrtJniUtil.c - Shared utility functions (checkOrtStatus, convertToValueInfo, convertOrtValueToONNXValue)
• OnnxModelMetadata.java - Java metadata class constructed by constructMetadata