Table of Contents

Interface IJVMWrapperDirect

Namespace
MASES.JCOBridge.C2JBridge.JVMInterop
Assembly
C2JBridge.dll

Public direct accessor for JVM: use this interface to directly manage objects and classes, this interface avoids use of dynamic resolution

public interface IJVMWrapperDirect
Extension Methods

Methods

CastTo(IJavaObjectBase, IJavaType, bool)

Creates from the origin a new IJavaObjectBase instance defined from clazz

IJavaObjectBase CastTo(IJavaObjectBase origin, IJavaType clazz, bool bypassConvertibilityCheck = false)

Parameters

origin IJavaObjectBase

The IJavaObjectBase to convert

clazz IJavaType

The IJavaType to convert to

bypassConvertibilityCheck bool

Default is false, set to true to verify convertibility

Returns

IJavaObjectBase

The new IJavaObjectBase converted instance

Remarks

The method checks the convertibility with IsAssignableFrom(IJavaType, IJavaType) and IsInstanceOf(IJavaObjectBase, IJavaType).

CastTo(IJavaObjectBase, string, bool)

Creates from the origin a new IJavaObjectBase instance defined from className

IJavaObjectBase CastTo(IJavaObjectBase origin, string className, bool bypassConvertibilityCheck = false)

Parameters

origin IJavaObjectBase

The IJavaObjectBase to convert

className string

The class name to convert to

bypassConvertibilityCheck bool

Default is false, set to true to verify convertibility

Returns

IJavaObjectBase

The new IJavaObjectBase converted instance

Remarks

The method checks the convertibility with IsAssignableFrom(IJavaType, IJavaType) and IsInstanceOf(IJavaObjectBase, IJavaType).

Convert(IJavaObjectBase, IJavaType, bool)

Converts the origin in an IJavaObjectBase instance defined from clazz

IJavaObjectBase Convert(IJavaObjectBase origin, IJavaType clazz, bool bypassConvertibilityCheck = false)

Parameters

origin IJavaObjectBase

The IJavaObjectBase to convert

clazz IJavaType

The IJavaType to convert to

bypassConvertibilityCheck bool

Default is false, set to true to verify convertibility

Returns

IJavaObjectBase

The IJavaObjectBase converted instance

Remarks

The method checks the convertibility with IsAssignableFrom(IJavaType, IJavaType) and IsInstanceOf(IJavaObjectBase, IJavaType). The original instance in origin cannot be used after the invocation of this method.

Convert(IJavaObjectBase, string, bool)

Converts the origin in an IJavaObjectBase instance defined from className

IJavaObjectBase Convert(IJavaObjectBase origin, string className, bool bypassConvertibilityCheck = false)

Parameters

origin IJavaObjectBase

The IJavaObjectBase to convert

className string

The class name to convert to

bypassConvertibilityCheck bool

Default is false, set to true to verify convertibility

Returns

IJavaObjectBase

The IJavaObjectBase converted instance

Remarks

The method checks the convertibility with IsAssignableFrom(IJavaType, IJavaType) and IsInstanceOf(IJavaObjectBase, IJavaType). The original instance in origin cannot be used after the invocation of this method.

ConvertObject(object)

Converts an object to its equivalent JVM type

object ConvertObject(object param)

Parameters

param object

The object to convert

Returns

object

The IntPtr representing the native pointer

GetClass(string)

Retrieve a class from JVM

IJavaType GetClass(string className)

Parameters

className string

The class name to retrieve

Returns

IJavaType

An IJavaType instance or null in case of error. Look in LastBindingException to check for possible problems.

GetClassName(IntPtr)

Gets the class name from the object pointer

string GetClassName(IntPtr jniRef)

Parameters

jniRef IntPtr

The native object pointer

Returns

string

A string representing the object in jniRef

GetDirectBuffer<T>(IJavaObject)

Returns a new instance of JCOBridgeDirectBuffer<T> holding the memory of the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html which belongs to obj

JCOBridgeDirectBuffer<T> GetDirectBuffer<T>(IJavaObject obj) where T : unmanaged

Parameters

obj IJavaObject

The https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html to read

Returns

JCOBridgeDirectBuffer<T>

A new instance of JCOBridgeDirectBuffer<T> holding the memory of the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html which belongs to obj

Type Parameters

T

The native type of the resulting JCOBridgeDirectBuffer<T>

GetDirectBuffer<T>(IJavaObject, bool)

Returns a new instance of JCOBridgeDirectBuffer<T> holding the memory of the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html which belongs to obj

JCOBridgeDirectBuffer<T> GetDirectBuffer<T>(IJavaObject obj, bool leaveOriginalOpen) where T : unmanaged

Parameters

obj IJavaObject

The https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html to read

leaveOriginalOpen bool

true to wraps in a new JCOBridgeDirectBuffer<T> instance and leaves obj alive, false to Dispose() the obj

Returns

JCOBridgeDirectBuffer<T>

A new instance of JCOBridgeDirectBuffer<T> holding the memory of the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html which belongs to obj

Type Parameters

T

The native type of the resulting JCOBridgeDirectBuffer<T>

GetObject(IntPtr, bool)

Gets an instance of IJavaObject from the object pointer

IJavaObjectBase GetObject(IntPtr jniRef, bool setGlobal)

Parameters

jniRef IntPtr

The native object pointer

setGlobal bool

true to set it as global reference

Returns

IJavaObjectBase

An IJavaObject instance

GetObject(string, IntPtr, bool)

Gets an instance of IJavaObject from the object pointer

IJavaObjectBase GetObject(string className, IntPtr jniRef, bool setGlobal)

Parameters

className string

The name of the class to be used

jniRef IntPtr

The native object pointer

setGlobal bool

true to set it as global reference

Returns

IJavaObjectBase

An IJavaObject instance

ImportPackage(string)

Imports a Java package to be used within the program

void ImportPackage(string packageName)

Parameters

packageName string

The package in the form of java.lang, java.util, etc.

Examples

To add package search use a code like:

// the following code is the Java equivalent of import java.lang.*;

ImportPackage("java.lang");

IsAssignableFrom(IJavaType, IJavaType)

Check if sub is assignable from sup

bool IsAssignableFrom(IJavaType sub, IJavaType sup)

Parameters

sub IJavaType

The IJavaType to check

sup IJavaType

The IJavaType to verify to

Returns

bool

true if sub is assignable from sup, otherwise false

IsInstanceOf(IJavaObjectBase, IJavaType)

Check if obj is instance of clazz

bool IsInstanceOf(IJavaObjectBase obj, IJavaType clazz)

Parameters

obj IJavaObjectBase

The IJavaObjectBase to check

clazz IJavaType

The IJavaType to verify to

Returns

bool

true if obj is instance of clazz, otherwise false

IsSameObject(IJavaObjectBase, IJavaObjectBase)

Check if the obj1 instance is the same reference of obj2 in the JVM

bool IsSameObject(IJavaObjectBase obj1, IJavaObjectBase obj2)

Parameters

obj1 IJavaObjectBase

First IJavaObjectBase to check

obj2 IJavaObjectBase

Second IJavaObjectBase to check against obj1

Returns

bool

true if obj1 and obj2 are the same object in the JVM, otherwise false

New(string)

Instantiates a new JVM object of className type using the no-argument constructor.

IJavaObjectBase New(string className)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no no-argument constructor is found on the underlying Java class.

New(string, object)

Instantiates a new JVM object of className type using a constructor that accepts 1 argument.

IJavaObjectBase New(string className, object arg0)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

arg0 object

The first argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument type.

New(string, object, object)

Instantiates a new JVM object of className type using a constructor that accepts 2 arguments.

IJavaObjectBase New(string className, object arg0, object arg1)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument types.

New(string, object, object, object)

Instantiates a new JVM object of className type using a constructor that accepts 3 arguments.

IJavaObjectBase New(string className, object arg0, object arg1, object arg2)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument types.

New(string, object, object, object, object)

Instantiates a new JVM object of className type using a constructor that accepts 4 arguments.

IJavaObjectBase New(string className, object arg0, object arg1, object arg2, object arg3)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument types.

New(string, object, object, object, object, object)

Instantiates a new JVM object of className type using a constructor that accepts 5 arguments.

IJavaObjectBase New(string className, object arg0, object arg1, object arg2, object arg3, object arg4)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument types.

New(string, object, object, object, object, object, object)

Instantiates a new JVM object of className type using a constructor that accepts 6 arguments.

IJavaObjectBase New(string className, object arg0, object arg1, object arg2, object arg3, object arg4, object arg5)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

arg5 object

The sixth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument types.

New(string, object, object, object, object, object, object, object)

Instantiates a new JVM object of className type using a constructor that accepts 7 arguments.

IJavaObjectBase New(string className, object arg0, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

arg5 object

The sixth argument to pass to the constructor.

arg6 object

The seventh argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument types.

New(string, object, object, object, object, object, object, object, object)

Instantiates a new JVM object of className type using a constructor that accepts 8 arguments.

IJavaObjectBase New(string className, object arg0, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

arg5 object

The sixth argument to pass to the constructor.

arg6 object

The seventh argument to pass to the constructor.

arg7 object

The eighth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument types.

New(string, object, object, object, object, object, object, object, object, object)

Instantiates a new JVM object of className type using a constructor that accepts 9 arguments.

IJavaObjectBase New(string className, object arg0, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

arg5 object

The sixth argument to pass to the constructor.

arg6 object

The seventh argument to pass to the constructor.

arg7 object

The eighth argument to pass to the constructor.

arg8 object

The ninth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument types.

New(string, object, object, object, object, object, object, object, object, object, object)

Instantiates a new JVM object of className type using a constructor that accepts 10 arguments.

IJavaObjectBase New(string className, object arg0, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

arg5 object

The sixth argument to pass to the constructor.

arg6 object

The seventh argument to pass to the constructor.

arg7 object

The eighth argument to pass to the constructor.

arg8 object

The ninth argument to pass to the constructor.

arg9 object

The tenth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument types.

New(string, params object[])

Instantiates a new JVM object of className type using a constructor that accepts 10 arguments.

IJavaObjectBase New(string className, params object[] args)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

args object[]

The argument for the class constructor

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no matching constructor is found for the given argument types.

NewArray(string, params object[])

Creates a new array

IJavaArray NewArray(string baseClass, params object[] data)

Parameters

baseClass string

The base class of the array

data object[]

The array elements

Returns

IJavaArray

An IJavaArray instance

NewArray<TArrayType>(params TArrayType[])

Creates a new array

IJavaArray NewArray<TArrayType>(params TArrayType[] data)

Parameters

data TArrayType[]

The array elements

Returns

IJavaArray

An IJavaArray instance

Type Parameters

TArrayType

The array type

NewDirectBuffer(MemoryStream, bool, EventHandler<MemoryStream>, int)

Creates a new https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html in the JVM by performing an internal copy of the content of stream.

JCOBridgeDirectBuffer<byte> NewDirectBuffer(MemoryStream stream, bool useMemoryControlBlock = false, EventHandler<MemoryStream> disposeEvent = null, int timeToLive = -1)

Parameters

stream MemoryStream

The non-disposed MemoryStream whose content will be copied into an internal buffer shared with the JVM via a https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html.

useMemoryControlBlock bool

NO MORE USED STARTING FROM VERSION 2.6.9 - Appends to the end of the stream a memory block used to control and arbitrate memory between CLR and JVM.

disposeEvent EventHandler<MemoryStream>

An optional EventHandler<TEventArgs> used to be informed when the internal copy derived from stream is no longer needed by the JVM, allowing the caller to dispose stream at the right time. If null, the underlying system will automatically dispose the MemoryStream.

timeToLive int

The time to live, expressed in milliseconds, the internal copy shall remain available; if the time to live expires the memory is retired leaving potentially the JVM under the possibility of an access violation.

Returns

JCOBridgeDirectBuffer<byte>

A new instance of JCOBridgeDirectBuffer<T> holding an internal copy of stream shared with the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html.

Remarks

Starting from version 2.6.9, the content of stream is no longer pinned in memory but copied into an internal buffer managed by the subsystem. Prior to version 2.6.9, the memory had to be pinned for the entire duration of the JVM usage to prevent access violations; the introduction of the internal copy removes this constraint, allowing stream to have an arbitrary lifetime without impacting the correctness of the operation. The internal copy remains available until the JVM reference of the newly created https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html is garbage collected. Under heavy pressure the memory footprint can raise up and generate an OutOfMemoryException, use the functionality with caution or take into account the timeToLive option which can help to recover the memory in advance before the Garbage Collector of the JVM retires the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html. If the user of JCOBridgeDirectBuffer<T> is pretty sure that the internal copy is no longer needed from the JVM, e.g. the invoked method does not queue the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html and its lifetime ends when the method returns, invoke Dispose() to immediately release unmanaged resources and free the memory.

High-rate scenarios: for activities with a high invocation rate, consider using Rent<T>(long) to obtain a pooled JCOBridgeSharedBufferStream<T>, fill it using Stream-based APIs, and then pass the populated instance to NewDirectBuffer<T>(JCOBridgeSharedBufferStream<T>). That overload automatically manages the lifecycle of the JCOBridgeSharedBufferStream<T> by returning it to the pool once the JVM Garbage Collector retires the associated https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html, avoiding repeated allocation and copy overhead.

Exceptions

NotSupportedException

Thrown when the JVM is unable to generate a https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html instance.

NewDirectBuffer(IntPtr, long, EventHandler<object>, object, int)

Creates a new https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html in the JVM which belongs to rawAddr.

JCOBridgeDirectBuffer<byte> NewDirectBuffer(IntPtr rawAddr, long capacity, EventHandler<object> disposeEvent = null, object disposeEventState = null, int timeToLive = -1)

Parameters

rawAddr IntPtr

The pointer where data is stored

capacity long

Declares the memory available, in byte, associated to rawAddr

disposeEvent EventHandler<object>

An optional Action<T> can be used to be informed when the rawAddr can be safely retired because the JVM is no longer using the pointer of rawAddr.

disposeEventState object

The data will be associated to disposeEvent, by default the value will be rawAddr

timeToLive int

The time to live, expressed in milliseconds, the underlying memory shall remain available; if the time to live expires the memory is retired leaving potentially the JVM under the possibility of an access violation.

Returns

JCOBridgeDirectBuffer<byte>

A new instance of JCOBridgeDirectBuffer<T> holding the memory of rawAddr shared with the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html

Remarks

The memory associated to rawAddr shall be available until the JVM reference of the newly created https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html is garbage collected to avoid access violation within the JVM. Under heavy pressure the memory footprint can raise up and generate an OutOfMemoryException, use the functionality with caution or take into account the timeToLive option which can help to recover the memory in advance before the Garbage Collector of the JVM retires the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html. If the user of JCOBridgeDirectBuffer<T> is pretty sure that the memory is no longer needed from the JVM, e.g. the invoked method does not queue the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html and its lifetime ends when the method returns, invoke Dispose() to immediately release unmanaged resources and free the memory.

Exceptions

NotSupportedException

Thrown when the JVM is unable to generate a https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html instance.

NewDirectBuffer<T>(JCOBridgeSharedBufferStream<T>)

Creates a new https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html in the JVM which shares the memory of stream. This is the preferred overload for high-rate scenarios as it avoids repeated array copies from CLR to JVM and benefits from pooled buffer management.

JCOBridgeDirectBuffer<T> NewDirectBuffer<T>(JCOBridgeSharedBufferStream<T> stream) where T : unmanaged

Parameters

stream JCOBridgeSharedBufferStream<T>

A JCOBridgeSharedBufferStream<T> obtained from Rent<T>(long) and populated via Stream-based APIs, to be used directly within the JVM from a https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html.

Returns

JCOBridgeDirectBuffer<T>

A new instance of JCOBridgeDirectBuffer<T> holding the memory of stream shared with the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html.

Type Parameters

T

The native type of the resulting JCOBridgeDirectBuffer<T>

Remarks

The memory associated to stream will be retained until the JVM reference of the newly created https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html is garbage collected. Under heavy pressure the memory footprint can raise up and generate an OutOfMemoryException; use the functionality with caution.

Lifecycle management: the subsystem automatically returns stream to the internal pool once the JVM Garbage Collector retires the associated https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html, i.e. when the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html has been fully consumed by the JVM. A direct call to Dispose() on the returned JCOBridgeDirectBuffer<T> is therefore a no-op; do not attempt to manually dispose stream after passing it to this method.

Pool strategy: the HPA (High Performance Application) runtime variant draws stream instances from a highly optimized pool tuned for high-throughput workloads, while the standard runtime variant uses a lighter pool. In both cases the pooling is fully transparent to the caller.

Exceptions

ArgumentException

Thrown when stream was not obtained through Rent<T>(long).

NotSupportedException

Thrown when the JVM is unable to generate a https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html instance.

NewDirectBuffer<T>(T[], bool, bool, int)

Creates a new https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html in the JVM by performing an internal copy of data.

JCOBridgeDirectBuffer<T> NewDirectBuffer<T>(T[] data, bool useMemoryControlBlock = false, bool arrangeCapacity = true, int timeToLive = -1) where T : unmanaged

Parameters

data T[]

The T array elements

useMemoryControlBlock bool

NO MORE USED STARTING FROM VERSION 2.6.9 - Appends to the end of the data a memory block used to control and arbitrate memory between CLR and JVM.

arrangeCapacity bool

If true the T array in data will be resized to the next power of 2, so capacity will be memory aligned and the limit of https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html will be the current size of data. However, if the T array in data needs a resize, the memory will be copied during the capacity arrangement; if arrangeCapacity is true, a good approach is to allocate an array which is a power of 2 at origin. If useMemoryControlBlock is true and there is no space left between capacity and limit, an extra resize is executed without considering the value of arrangeCapacity.

timeToLive int

The time to live, expressed in milliseconds, the underlying memory shall remain available; if the time to live expires the internal copy is retired leaving potentially the JVM under the possibility of an access violation.

Returns

JCOBridgeDirectBuffer<T>

A new instance of JCOBridgeDirectBuffer<T> holding an internal copy of data shared with the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html

Type Parameters

T

The native type of the resulting JCOBridgeDirectBuffer<T>

Remarks

Starting from version 2.6.9, the content of data is no longer pinned in memory but copied into an internal buffer managed by the subsystem. Prior to version 2.6.9, the memory had to be pinned for the entire duration of the JVM usage to prevent access violations; the introduction of the internal copy removes this constraint, allowing data to have an arbitrary lifetime without impacting the correctness of the operation. The internal copy remains available until the JVM reference of the newly created https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html is garbage collected. Under heavy pressure the memory footprint can raise up and generate an OutOfMemoryException, use the functionality with caution or take into account the timeToLive option which can help to recover the memory in advance before the Garbage Collector of the JVM retires the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html. If the user of JCOBridgeDirectBuffer<T> is pretty sure that the internal copy is no longer needed from the JVM, e.g. the invoked method does not queue the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html and its lifetime ends when the method returns, invoke Dispose() to immediately release unmanaged resources and free the memory.

High-rate scenarios: for activities with a high invocation rate, consider using Rent<T>(long) to obtain a pooled JCOBridgeSharedBufferStream<T>, fill it using Stream-based APIs, and then pass the populated instance to NewDirectBuffer<T>(JCOBridgeSharedBufferStream<T>). That overload automatically manages the lifecycle of the JCOBridgeSharedBufferStream<T> by returning it to the pool once the JVM Garbage Collector retires the associated https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html, avoiding repeated allocation and copy overhead.

Exceptions

NotSupportedException

Thrown when the JVM is unable to generate a https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html instance.

NewWithSignature(string, string)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and no arguments.

IJavaObjectBase NewWithSignature(string className, string signature)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Remarks

Use this overload when multiple constructors share ambiguous argument types and the bridge cannot resolve the correct one automatically. The JNI signature format follows the standard Java descriptor notation, e.g. "()V" for a no-argument constructor.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, object)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and 1 argument.

IJavaObjectBase NewWithSignature(string className, string signature, object arg0)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

arg0 object

The first argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, object, object)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and 2 arguments.

IJavaObjectBase NewWithSignature(string className, string signature, object arg0, object arg1)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, object, object, object)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and 3 arguments.

IJavaObjectBase NewWithSignature(string className, string signature, object arg0, object arg1, object arg2)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, object, object, object, object)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and 4 arguments.

IJavaObjectBase NewWithSignature(string className, string signature, object arg0, object arg1, object arg2, object arg3)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, object, object, object, object, object)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and 5 arguments.

IJavaObjectBase NewWithSignature(string className, string signature, object arg0, object arg1, object arg2, object arg3, object arg4)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, object, object, object, object, object, object)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and 6 arguments.

IJavaObjectBase NewWithSignature(string className, string signature, object arg0, object arg1, object arg2, object arg3, object arg4, object arg5)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

arg5 object

The sixth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, object, object, object, object, object, object, object)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and 7 arguments.

IJavaObjectBase NewWithSignature(string className, string signature, object arg0, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

arg5 object

The sixth argument to pass to the constructor.

arg6 object

The seventh argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, object, object, object, object, object, object, object, object)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and 8 arguments.

IJavaObjectBase NewWithSignature(string className, string signature, object arg0, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

arg5 object

The sixth argument to pass to the constructor.

arg6 object

The seventh argument to pass to the constructor.

arg7 object

The eighth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, object, object, object, object, object, object, object, object, object)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and 9 arguments.

IJavaObjectBase NewWithSignature(string className, string signature, object arg0, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

arg5 object

The sixth argument to pass to the constructor.

arg6 object

The seventh argument to pass to the constructor.

arg7 object

The eighth argument to pass to the constructor.

arg8 object

The ninth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, object, object, object, object, object, object, object, object, object, object)

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and 10 arguments.

IJavaObjectBase NewWithSignature(string className, string signature, object arg0, object arg1, object arg2, object arg3, object arg4, object arg5, object arg6, object arg7, object arg8, object arg9)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

arg0 object

The first argument to pass to the constructor.

arg1 object

The second argument to pass to the constructor.

arg2 object

The third argument to pass to the constructor.

arg3 object

The fourth argument to pass to the constructor.

arg4 object

The fifth argument to pass to the constructor.

arg5 object

The sixth argument to pass to the constructor.

arg6 object

The seventh argument to pass to the constructor.

arg7 object

The eighth argument to pass to the constructor.

arg8 object

The ninth argument to pass to the constructor.

arg9 object

The tenth argument to pass to the constructor.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

NewWithSignature(string, string, params object[])

Instantiates a new JVM object of className type using the constructor identified by an explicit JNI signature and a variable-length argument list.

IJavaObjectBase NewWithSignature(string className, string signature, params object[] args)

Parameters

className string

The class name in the dot or slash form (example are java.lang.Boolean or java/lang/Boolean)

signature string

The JNI constructor descriptor string that uniquely identifies the target constructor.

args object[]

The arguments to pass to the constructor. Each element must be compatible with the corresponding Java parameter type declared in signature.

Returns

IJavaObjectBase

A new IJavaObjectBase wrapping the newly created JVM instance.

Remarks

The explicit signature is resolved at the JNI level before dispatching the call, so this overload is suitable when multiple constructors share the same parameter count and the bridge cannot unambiguously select the right one from the argument types alone. For a fixed, known number of arguments (0–5), prefer the strongly-typed overloads to avoid the overhead of array allocation.

Exceptions

MissingMethodException

Thrown if no constructor matching signature is found on the underlying Java class.

Rent<T>(long)

Returns a JCOBridgeSharedBufferStream<T> with an initial capacity derived from capacity, to be populated via Stream-based APIs and then passed to NewDirectBuffer<T>(JCOBridgeSharedBufferStream<T>).

JCOBridgeSharedBufferStream<T> Rent<T>(long capacity = -1) where T : unmanaged

Parameters

capacity long

The plausible number of elements of T type to be written into the stream; the byte size is computed as capacity * sizeof(T). The default value of -1 instructs the subsystem to allocate the minimum meaningful unit, which corresponds to one system memory page (see SystemPageSize). Regardless of the value provided, the effective allocation is always rounded up to the nearest multiple of the system page size, since the underlying native allocator operates at page granularity. Passing a value smaller than one page therefore has no practical advantage over using the default. This value is a hint, not a hard limit: if the actual data written exceeds the initial allocation, the underlying buffer will grow automatically via reallocation. However, providing a value greater than or equal to the actual data size is strongly recommended to avoid reallocation overhead, especially in high-rate scenarios. Callers that process data of a known or predictable size are encouraged to implement their own estimation strategy — for example, tracking the stable size observed in previous invocations — so that the initial capacity converges toward the real value over time and reallocations become increasingly rare or disappear entirely.

Returns

JCOBridgeSharedBufferStream<T>

A pooled instance of JCOBridgeSharedBufferStream<T> ready to be written via Stream-based APIs and then passed to NewDirectBuffer<T>(JCOBridgeSharedBufferStream<T>).

Type Parameters

T

The Type to be used: it can be any byte, short, int, long, float, double or a type defined as a struct.

Remarks

The returned JCOBridgeSharedBufferStream<T> is drawn from an internal pool. The HPA (High Performance Application) runtime variant uses a highly optimized pool tuned for high-throughput scenarios, while the standard runtime variant uses a lighter pool suitable for moderate workloads. The instance must not be manually disposed; its lifecycle is fully managed by the subsystem and it is automatically returned to the pool once the JVM Garbage Collector retires the associated https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html created by NewDirectBuffer<T>(JCOBridgeSharedBufferStream<T>).

Exceptions

ArgumentOutOfRangeException

Thrown when capacity is zero or any positive value that, once multiplied by sizeof(T), overflows a long.

Throw(IJavaObjectBase)

Throws an exception

void Throw(IJavaObjectBase obj)

Parameters

obj IJavaObjectBase

The IJavaObjectBase containing exception

ToArray(IJavaObject, bool)

Gets an instance of IJavaObject from the object pointer

IJavaArray ToArray(IJavaObject obj, bool setGlobal)

Parameters

obj IJavaObject

The IJavaObject to convert

setGlobal bool

true to set it as global reference

Returns

IJavaArray

An IJavaArray instance

ToJavaException(IJavaObject, bool)

Converts exceptionObject to a JavaException

JavaException ToJavaException(IJavaObject exceptionObject, bool force = false)

Parameters

exceptionObject IJavaObject

The JVM exception object

force bool

true to check if exceptionObject is a Throwable

Returns

JavaException

The JavaException created from exceptionObject