T - the type of the wrapped object.public final class JCRefOut<T> extends Object
ref / out) across the JNI boundary.
CLR methods that accept ref or out parameters cannot be called directly
from Java because Java has no pass-by-reference semantics for object references. JCRefOut
solves this by wrapping the argument in a mutable container: the bridge writes the CLR-side
result back into the container via setObject(Object) or setObject(Object[]),
and the caller reads the updated value via getObject().
Supported container types for the wrapped object:
byte[], int[], long[], etc.) — the bridge
writes back into the same array instance.AtomicReference — updated atomically via AtomicReference.set(V).AtomicBoolean, AtomicInteger, AtomicLong — updated atomically.AtomicIntegerArray, AtomicLongArray — element-by-element update.getObject() after the CLR call returns).Use Create(Object) or Create(Object[]) as the primary factory methods.
The referenceStorage overloads (Create(Object, Object),
Create(Object[], Object)) accept an additional object whose sole purpose is to
prevent premature GC collection of an object that must stay alive for the duration of the
CLR call.
See also: JCOReflector for usage examples.
| Modifier and Type | Method and Description |
|---|---|
static <T> JCRefOut<T> |
Create(T refObj)
Creates a
JCRefOut wrapping a scalar object. |
static <T> JCRefOut<T> |
Create(T[] refObj)
Creates a
JCRefOut wrapping an array object. |
static <T> JCRefOut<T> |
Create(T[] refObj,
Object referenceStorage)
Creates a
JCRefOut wrapping an array object, with an additional GC anchor. |
static <T> JCRefOut<T> |
Create(T refObj,
Object referenceStorage)
Creates a
JCRefOut wrapping a scalar object, with an additional GC anchor. |
static <T> JCRefOut<T> |
CreateOut(T refObj)
Deprecated.
Use
Create(Object) instead. |
static <T> JCRefOut<T> |
CreateRef(T refObj)
Deprecated.
Use
Create(Object) instead. |
Object |
getObject()
Returns the current value of the wrapped object in a form suitable for passing
across the JNI boundary to the CLR.
|
boolean |
isRef()
Deprecated.
This flag is not used by the current bridge implementation.
|
void |
setObject(Object refObj)
Writes the CLR result back into the wrapped container after the CLR call returns.
|
<Y> void |
setObject(Y[] refObj)
Writes a CLR array result back into the wrapped array container after the CLR call returns.
|
@Deprecated public static <T> JCRefOut<T> CreateRef(T refObj)
Create(Object) instead.JCRefOut for a ref parameter.T - the type of the wrapped object.refObj - the initial value.JCRefOut wrapping refObj.@Deprecated public static <T> JCRefOut<T> CreateOut(T refObj)
Create(Object) instead.JCRefOut for an out parameter.T - the type of the wrapped object.refObj - the initial value (typically ignored by the CLR for pure out).JCRefOut wrapping refObj.public static <T> JCRefOut<T> Create(T refObj)
JCRefOut wrapping a scalar object.
The wrapped object may be a primitive array (byte[], int[], etc.),
an AtomicReference, AtomicBoolean, AtomicInteger,
AtomicLong, AtomicIntegerArray, or AtomicLongArray.
The bridge will write the CLR result back into the container after the call.
T - the type of the wrapped object.refObj - the object to wrap and pass to the CLR.JCRefOut wrapping refObj.public static <T> JCRefOut<T> Create(T refObj, Object referenceStorage)
JCRefOut wrapping a scalar object, with an additional GC anchor.
Use this overload when refObj references an object that must be kept alive
for the duration of the CLR call but might otherwise be collected (e.g. a temporary
wrapper whose only live reference is inside the CLR side).
T - the type of the wrapped object.refObj - the object to wrap and pass to the CLR.referenceStorage - an object to keep alive alongside refObj; may be null.JCRefOut wrapping refObj.public static <T> JCRefOut<T> Create(T[] refObj)
JCRefOut wrapping an array object.
The array may be a primitive array (byte[], int[], etc.) or
any object array. The bridge will write CLR results back into the same array
instance element by element.
T - the component type of the array.refObj - the array to wrap and pass to the CLR.JCRefOut wrapping refObj.public static <T> JCRefOut<T> Create(T[] refObj, Object referenceStorage)
JCRefOut wrapping an array object, with an additional GC anchor.T - the component type of the array.refObj - the array to wrap and pass to the CLR.referenceStorage - an object to keep alive alongside refObj; may be null.JCRefOut wrapping refObj.@Deprecated public boolean isRef()
ref/out flag.true if this wrapper was created with ref semantics.public Object getObject()
For atomic types, the current atomic value is extracted. For
AtomicIntegerArray and AtomicLongArray, a new primitive array
is allocated and filled with a snapshot of the atomic array contents.
For all other types, the raw wrapped object is returned directly.
null for atomic types.public void setObject(Object refObj)
The update strategy depends on the wrapped type:
AtomicReference — updated via AtomicReference.set(V).AtomicBoolean, AtomicInteger, AtomicLong — updated
atomically with an unboxing cast.mrefObj is replaced by direct assignment. The caller
must re-read getObject() to obtain the updated value.refObj - the value returned by the CLR for this ref/out parameter.public <Y> void setObject(Y[] refObj)
The update strategy depends on the wrapped type:
AtomicIntegerArray — each element is updated via
AtomicIntegerArray.set(int, int), with an unboxing cast to int.AtomicLongArray — each element is updated via
AtomicLongArray.set(int, long), with an unboxing cast to long.null result — mrefObj is set to null.min(mrefObj.length, refObj.length) positions via Array.set(java.lang.Object, int, java.lang.Object).
If mrefObj is null, it is replaced by refObj.Y - the component type of the returned array.refObj - the array value returned by the CLR for this ref/out parameter.