Implementation:Microsoft Onnxruntime OnnxTensor

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

Domains

• Machine Learning Runtime
• Dense Tensor Representation
• JNI Native Interop

Overview

OnnxTensor is the primary class for representing dense tensors in the ONNX Runtime Java API. It wraps a native OrtValue pointer and provides factory methods to create tensors from Java arrays, NIO buffers, and strings. It supports all standard ONNX data types including float, double, int8/16/32/64, uint8, bool, string, fp16, and bf16. The class implements zero-copy tensor creation when using direct NIO buffers and automatic fp16/bf16 to fp32 upconversion on extraction.

Description

The OnnxTensor class extends OnnxTensorLike and provides:

• Tensor creation from arrays: createTensor(OrtEnvironment, Object) accepts Java primitives, boxed primitives, or multidimensional arrays and infers the shape via reflection.
• Tensor creation from buffers: Overloaded createTensor methods accept FloatBuffer, DoubleBuffer, ByteBuffer, ShortBuffer, IntBuffer, and LongBuffer with explicit shape arrays. Direct buffers enable zero-copy transfer.
• String tensors: createTensor(OrtEnvironment, String[], long[]) creates string tensors from flattened arrays.
• Value extraction: getValue() returns boxed primitives for scalars or multidimensional Java arrays for non-scalars. FP16 and BF16 values are automatically upcast to float.
• Buffer extraction: Methods like getFloatBuffer(), getDoubleBuffer(), getByteBuffer(), getShortBuffer(), getIntBuffer(), getLongBuffer() return typed buffer copies.
• Buffer reference: getBufferRef() returns an optional reference to the backing buffer for in-place mutation.
• Ownership tracking: ownsBuffer() indicates whether the tensor owns a copy of the backing buffer.

Usage

Create tensors as inputs for inference sessions, then extract outputs as Java values or buffers.

Code Reference

Source Location

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

Signature

public class OnnxTensor extends OnnxTensorLike {
    // Factory methods
    public static OnnxTensor createTensor(OrtEnvironment env, Object data) throws OrtException;
    public static OnnxTensor createTensor(OrtEnvironment env, String[] data, long[] shape) throws OrtException;
    public static OnnxTensor createTensor(OrtEnvironment env, FloatBuffer data, long[] shape) throws OrtException;
    public static OnnxTensor createTensor(OrtEnvironment env, DoubleBuffer data, long[] shape) throws OrtException;
    public static OnnxTensor createTensor(OrtEnvironment env, ByteBuffer data, long[] shape) throws OrtException;
    public static OnnxTensor createTensor(OrtEnvironment env, ByteBuffer data, long[] shape, OnnxJavaType type) throws OrtException;
    public static OnnxTensor createTensor(OrtEnvironment env, ShortBuffer data, long[] shape) throws OrtException;
    public static OnnxTensor createTensor(OrtEnvironment env, ShortBuffer data, long[] shape, OnnxJavaType type) throws OrtException;
    public static OnnxTensor createTensor(OrtEnvironment env, IntBuffer data, long[] shape) throws OrtException;
    public static OnnxTensor createTensor(OrtEnvironment env, LongBuffer data, long[] shape) throws OrtException;

    // Value extraction
    public Object getValue() throws OrtException;
    public OnnxValueType getType();
    public boolean ownsBuffer();
    public Optional<Buffer> getBufferRef();

    // Buffer extraction
    public ByteBuffer getByteBuffer();
    public FloatBuffer getFloatBuffer();
    public DoubleBuffer getDoubleBuffer();
    public ShortBuffer getShortBuffer();
    public IntBuffer getIntBuffer();
    public LongBuffer getLongBuffer();

    public synchronized void close();
}

Import

import ai.onnxruntime.OnnxTensor;

I/O Contract

Inputs

Name	Type	Description
env	OrtEnvironment	The ONNX Runtime environment
data	Object / Buffer / String[]	The tensor data (array, NIO buffer, or string array)
shape	long[]	The tensor shape (required for buffer-based creation)
type	OnnxJavaType	Optional type hint for ByteBuffer and ShortBuffer variants

Outputs

Name	Type	Description
OnnxTensor	OnnxTensor	Wraps a native ORT tensor value
getValue()	Object	Boxed primitive (scalar) or multidimensional Java array
getFloatBuffer()	FloatBuffer	Copy of tensor data as floats (also handles fp16/bf16 upconversion)
getByteBuffer()	ByteBuffer	Raw byte copy of tensor data

Usage Examples

import ai.onnxruntime.*;
import java.nio.FloatBuffer;
import java.util.*;

OrtEnvironment env = OrtEnvironment.getEnvironment();

// Create a tensor from a 2D float array
float[][] inputData = {{1.0f, 2.0f, 3.0f}, {4.0f, 5.0f, 6.0f}};
try (OnnxTensor tensor = OnnxTensor.createTensor(env, inputData)) {
    System.out.println(tensor); // OnnxTensor(info=TensorInfo(...),closed=false)
}

// Create a tensor from a direct FloatBuffer (zero-copy)
FloatBuffer directBuf = FloatBuffer.allocate(6);
directBuf.put(new float[]{1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f});
directBuf.rewind();
try (OnnxTensor tensor = OnnxTensor.createTensor(env, directBuf, new long[]{2, 3})) {
    FloatBuffer output = tensor.getFloatBuffer();
    System.out.println("First element: " + output.get(0));
}

// Create a scalar string tensor
try (OnnxTensor tensor = OnnxTensor.createTensor(env, "hello world")) {
    String value = (String) tensor.getValue();
    System.out.println("String value: " + value);
}

Related Pages

• OnnxSparseTensor.java - Sparse tensor counterpart
• TensorInfo.java - Tensor metadata and shape information
• ai_onnxruntime_OnnxTensor.c - JNI native implementation
• OrtUtil.java - Array-to-buffer conversion utilities
• OrtEnvironment.java - Environment required for tensor creation