Implementation:Microsoft Onnxruntime OrtEnvironment

Knowledge Sources	Description
Source File	java/src/main/java/ai/onnxruntime/OrtEnvironment.java
Repository	Microsoft/onnxruntime

Domains

• Machine Learning Runtime
• Environment Management
• Session Factory

Overview

OrtEnvironment is the host object for the ONNX Runtime system. It follows the singleton pattern -- at most one instance can exist per JVM lifetime. It creates OrtSession and OrtTrainingSession instances, manages execution provider discovery, controls telemetry, and provides access to EP device enumeration and model compatibility checks. The environment is closed automatically via a JVM shutdown hook.

Description

The OrtEnvironment class provides:

• Singleton access: Multiple getEnvironment() overloads return the singleton, creating it on first access with configurable logging level and name.
• Thread pool configuration: getEnvironment(OrtLoggingLevel, String, ThreadingOptions) creates an environment with global thread pools (throws if environment already exists).
• Session creation: Overloaded createSession methods accept model path strings, byte arrays, or direct ByteBuffers, with optional SessionOptions.
• Training session creation: createTrainingSession methods create training sessions from checkpoint, train, eval, and optimizer model paths.
• Provider discovery: getAvailableProviders() returns an EnumSet<OrtProvider> of available execution providers.
• EP device enumeration: getEpDevices() lists all execution provider and device combinations. getModelCompatibilityForEpDevices() checks model compatibility.
• EP library registration: registerExecutionProviderLibrary() and unregisterExecutionProviderLibrary() manage dynamic EP registration.
• Telemetry control: setTelemetry(boolean) enables or disables usage telemetry.
• Version: getVersion() returns the native library version string.
• Inner classes: ThreadingOptions configures global thread pool sizes, spin control, and denormal handling. OrtCompiledModelCompatibility enum represents model compatibility states.

Usage

Obtain the environment singleton, then use it to create inference or training sessions.

Code Reference

Source Location

// File: java/src/main/java/ai/onnxruntime/OrtEnvironment.java
// Package: ai.onnxruntime

Signature

public final class OrtEnvironment implements AutoCloseable {
    public static final String DEFAULT_NAME = "ort-java";

    public static synchronized OrtEnvironment getEnvironment();
    public static OrtEnvironment getEnvironment(String name);
    public static OrtEnvironment getEnvironment(OrtLoggingLevel logLevel);
    public static synchronized OrtEnvironment getEnvironment(OrtLoggingLevel loggingLevel, String name);
    public static synchronized OrtEnvironment getEnvironment(
        OrtLoggingLevel loggingLevel, String name, ThreadingOptions threadOptions);

    public OrtSession createSession(String modelPath) throws OrtException;
    public OrtSession createSession(String modelPath, SessionOptions options) throws OrtException;
    public OrtSession createSession(ByteBuffer modelBuffer) throws OrtException;
    public OrtSession createSession(ByteBuffer modelBuffer, SessionOptions options) throws OrtException;
    public OrtSession createSession(byte[] modelArray) throws OrtException;
    public OrtSession createSession(byte[] modelArray, SessionOptions options) throws OrtException;

    public OrtTrainingSession createTrainingSession(
        String checkpointPath, String trainPath, String evalPath, String optimizerPath) throws OrtException;
    public OrtTrainingSession createTrainingSession(
        String checkpointPath, String trainPath, String evalPath,
        String optimizerPath, SessionOptions options) throws OrtException;

    public boolean isTrainingEnabled();
    public void setTelemetry(boolean sendTelemetry) throws OrtException;
    public String getVersion();
    public static EnumSet<OrtProvider> getAvailableProviders();
    public void registerExecutionProviderLibrary(String registrationName, String libraryPath) throws OrtException;
    public void unregisterExecutionProviderLibrary(String registrationName) throws OrtException;
    public List<OrtEpDevice> getEpDevices() throws OrtException;
    public OrtCompiledModelCompatibility getModelCompatibilityForEpDevices(
        List<OrtEpDevice> epDevices, String modelInfo) throws OrtException;
    public void close(); // no-op since ORT 1.11

    // Inner classes
    public static final class ThreadingOptions implements AutoCloseable { ... }
    public enum OrtCompiledModelCompatibility { EP_NOT_APPLICABLE, EP_SUPPORTED_OPTIMAL,
        EP_SUPPORTED_PREFER_RECOMPILATION, EP_UNSUPPORTED }
}

Import

import ai.onnxruntime.OrtEnvironment;

I/O Contract

Inputs

Name	Type	Description
loggingLevel	OrtLoggingLevel	The logging level for the environment
name	String	The logging identifier for the environment
modelPath	String	Path on disk to the ONNX model
modelBuffer	ByteBuffer	Direct byte buffer containing model bytes
modelArray	byte[]	Byte array containing model bytes
options	SessionOptions	Configuration for the session

Outputs

Name	Type	Description
OrtEnvironment	OrtEnvironment	The singleton environment instance
OrtSession	OrtSession	An inference session wrapping the loaded model
OrtTrainingSession	OrtTrainingSession	A training session wrapping the loaded models
getVersion()	String	The ORT native library version
getAvailableProviders()	EnumSet<OrtProvider>	Available execution providers

Usage Examples

import ai.onnxruntime.*;

// Get the default environment
OrtEnvironment env = OrtEnvironment.getEnvironment();
System.out.println("ONNX Runtime version: " + env.getVersion());
System.out.println("Providers: " + OrtEnvironment.getAvailableProviders());

// Create a session with custom options
try (OrtSession.SessionOptions opts = new OrtSession.SessionOptions()) {
    opts.setOptimizationLevel(OrtSession.SessionOptions.OptLevel.ALL_OPT);
    opts.setIntraOpNumThreads(4);

    try (OrtSession session = env.createSession("/path/to/model.onnx", opts)) {
        System.out.println("Inputs: " + session.getInputNames());
        System.out.println("Outputs: " + session.getOutputNames());
    }
}

// Create an environment with global thread pool options
try (OrtEnvironment.ThreadingOptions threadOpts = new OrtEnvironment.ThreadingOptions()) {
    threadOpts.setGlobalIntraOpNumThreads(4);
    threadOpts.setGlobalInterOpNumThreads(2);
    // Note: only works if no environment exists yet
}

Related Pages

• OrtSession.java - Inference session created by the environment
• OrtTrainingSession.java - Training session created by the environment
• OnnxRuntime.java - Native library loader triggered by the environment
• OrtLoggingLevel.java - Logging level enum used by the environment
• OrtProvider.java - Execution provider enum