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)

Converts the origin in the 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 IJavaObjectBase converted instance

Remarks

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

CastTo(IJavaObjectBase, string, bool)

Converts the origin in the 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 IJavaObjectBase converted instance

Remarks

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

ConvertObject(object)

Converts an object to its equivalent JVM type

IntPtr ConvertObject(object param)

Parameters

param object

The object to convert

Returns

IntPtr

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)

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>

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

New(string, params object[])

Create a new JVM object

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

An IJavaObject instance

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 which shares the stream. The method helps to avoid too many array copies from CLR to JVM

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

Parameters

stream MemoryStream

The non disposed MemoryStream to be used directly within the JVM from a https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html, see remarks

useMemoryControlBlock bool

Appends to the end of the stream a memory block will be used to controls and arbitrates memory between CLR and JVM

disposeEvent EventHandler<MemoryStream>

An optional EventHandler<TEventArgs> can be used to be informed when the stream can be safely disposed (the dispose action shall be in the user code), if null the underlying system will automatically dispose the MemoryStream.

timeToLive int

The time to live, expressed in milliseconds, the underlying memory shall remain available; if the time to live expires the pinned 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 stream shared with the https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html

Remarks

The memory associated to stream will be pinned 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 pinned memory is no more 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

The MemoryStream cannot be disposed otherwise the underlying system is not able to access the memory. The MemoryStream can be written, or read, and changes are visible to both CLR and JVM, however, if the MemoryStream grows, the underlying system cannot resize too and capacity still remains the one when NewDirectBuffer(MemoryStream, bool, EventHandler<MemoryStream>, int) was invoked the first time.

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 EventHandler<TEventArgs> can be used to be informed when the rawAddr can be safely retired becuase the JVM is no moore 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 more 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

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

Creates a new https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html in the JVM which belongs to data. If this method is used in conjunction with arrangeCapacity and/or useMemoryControlBlock set to true, better performances are obtained from NewDirectBuffer(MemoryStream, bool, EventHandler<MemoryStream>, int) becuase MemoryStream automatically manages its capacity and, in general, will be the memory space available for control memory block needed from useMemoryControlBlock set to true

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

Parameters

data T[]

The T array elements

useMemoryControlBlock bool

Appends to the end of the data a memory block will be used to controls and arbitrates 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 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 2 at origin. If useMemoryControlBlock is true and there is no space left, between capacity and limit, an extra resize is executed without consider 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 pinned memory is retired leaving potentially the JVM under the possibility of an access violation.

Returns

JCOBridgeDirectBuffer<T>

A new instance of JCOBridgeDirectBuffer<T> holding the memory 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

The memory associated to data will be pinned 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 pinned memory is no more 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

NewWithSignature(string, string, params object[])

Create a new JVM object

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 constructor signature to be used

args object[]

The argument for the class constructor

Returns

IJavaObjectBase

An IJavaObject instance

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