org.mases.jcobridge

Class JCObject

java.lang.Object

org.mases.jcobridge.JCHandler

org.mases.jcobridge.JCObject

All Implemented Interfaces:

Cloneable, Iterable<JCObject>

public final class JCObject
extends JCHandler
implements Iterable<JCObject>, Cloneable

JVM-side proxy for a CLR object instance.

JCObject holds a native reference to a live CLR object and exposes methods to invoke instance and type-level members, get and set properties and fields, and register or unregister CLR event handlers. All member accesses cross the JNI boundary and are executed within the CLR context.

Return values from member invocations follow a fixed mapping rule: CLR primitive types (bool, int, float, String, etc.) are returned as their Java equivalents, while all other CLR types are returned as a new JCObject.

JCObject instances must not be constructed directly. Use JCOBridge.NewObject(java.lang.String, java.lang.Object...) or JCType.NewObject(java.lang.Object...) to obtain valid instances.

JCObject implements Iterable so that CLR collections and enumerables can be iterated with a standard Java for-each loop.

See also: JCOReflector for usage examples.

Since:

1.0.0.0

Author:

MASES S.R.L.

Method Summary

Modifier and Type	Method and Description
Object	clone() Creates and returns a deep copy of this CLR object by invoking the CLR Clone method on the underlying object.
boolean	equals(Object obj) Tests equality with another object by delegating to the CLR Equals method on the underlying CLR object.
Object	Get(String propertyName) Retrieves an instance property value from the underlying CLR object.
Object	GetField(String field) Retrieves an instance field value from the underlying CLR object.
Object	GetOnType(String propertyName) Retrieves a static or type-level property value from the CLR type of the underlying object.
int	hashCode() Returns the hash code of the underlying CLR object by delegating to the CLR GetHashCode method.
Object	Invoke(String method, Object... params) Invokes an instance method on the underlying CLR object with optional arguments.
Object	InvokeOnType(String method, Object... params) Invokes a static or type-level method on the CLR type of the underlying object, rather than on the object instance itself.
Iterator<JCObject>	iterator() Returns an iterator over the elements of the underlying CLR collection or enumerable.
void	RegisterEventListener(String eventName, IJCEventEmit eventHandler) Registers a value-returning CLR event handler on this object.
void	RegisterEventListener(String eventName, IJCVoidEventEmit eventHandler) Registers a void-return CLR event handler on this object.
JCObject	Set(String propertyName, Object value) Sets an instance property on the underlying CLR object.
JCObject	SetField(String field, Object value) Sets an instance field on the underlying CLR object.
String	toString() Returns the string representation of the underlying CLR object by delegating to the CLR ToString method.
void	UnregisterEventListener(String eventName, IJCEventEmit eventHandler) Unregisters a value-returning CLR event handler from this object.
void	UnregisterEventListener(String eventName, IJCVoidEventEmit eventHandler) Unregisters a void-return CLR event handler from this object.

Methods inherited from class org.mases.jcobridge.JCHandler

getReference

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

clone

public Object clone()
             throws CloneNotSupportedException

Creates and returns a deep copy of this CLR object by invoking the CLR Clone method on the underlying object. The CLR type must implement ICloneable.

Overrides:

clone in class Object

Returns:

a new JCObject wrapping the cloned CLR object.

Throws:

CloneNotSupportedException - if the CLR type does not support cloning or if the native call fails.

equals

public boolean equals(Object obj)

Tests equality with another object by delegating to the CLR Equals method on the underlying CLR object. Returns false if the native call fails.

Overrides:

equals in class Object

Parameters:

obj - the reference object to compare with.

Returns:

true if the CLR object considers itself equal to obj.

hashCode

public int hashCode()

Returns the hash code of the underlying CLR object by delegating to the CLR GetHashCode method.

Overrides:

hashCode in class Object

Returns:

the CLR hash code.

toString

public String toString()

Returns the string representation of the underlying CLR object by delegating to the CLR ToString method.

Overrides:

toString in class Object

Returns:

the CLR string representation.

iterator

public Iterator<JCObject> iterator()

Returns an iterator over the elements of the underlying CLR collection or enumerable. The CLR type must implement IEnumerable. Returns null if the native iterator cannot be created.

Specified by:

iterator in interface Iterable<JCObject>

Returns:

an Iterator over the CLR collection elements, each wrapped as a JCObject, or null on failure.

Since:

1.0.0.0

Invoke

public Object Invoke(String method,
                     Object... params)
              throws JCNativeException

Invokes an instance method on the underlying CLR object with optional arguments.

The method is resolved by name on the CLR type of the object. If overloads exist, the bridge selects the best match based on the argument types. Return values follow the standard mapping: CLR primitives become Java primitives or String; all other types are returned as JCObject.

Parameters:

method - the name of the CLR instance method to invoke.

params - optional arguments to pass to the method.

Returns:

the method return value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the method cannot be found, the invocation fails, or a CLR exception is thrown.

Get

public Object Get(String propertyName)
           throws JCNativeException

Retrieves an instance property value from the underlying CLR object.

Parameters:

propertyName - the name of the CLR property to read.

Returns:

the property value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the property cannot be found or the read fails.

GetField

public Object GetField(String field)
                throws JCNativeException

Retrieves an instance field value from the underlying CLR object.

Parameters:

field - the name of the CLR field to read.

Returns:

the field value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the field cannot be found or the read fails.

Set

public JCObject Set(String propertyName,
                    Object value)
             throws JCNativeException

Sets an instance property on the underlying CLR object.

Parameters:

propertyName - the name of the CLR property to write.

value - the value to assign.

Returns:

this JCObject instance, for call chaining.

Throws:

JCNativeException - if the property cannot be found or the write fails.

SetField

public JCObject SetField(String field,
                         Object value)
                  throws JCNativeException

Sets an instance field on the underlying CLR object.

Parameters:

field - the name of the CLR field to write.

value - the value to assign.

Returns:

this JCObject instance, for call chaining.

Throws:

JCNativeException - if the field cannot be found or the write fails.

InvokeOnType

public Object InvokeOnType(String method,
                           Object... params)
                    throws JCNativeException

Invokes a static or type-level method on the CLR type of the underlying object, rather than on the object instance itself.

Parameters:

method - the name of the CLR type-level method to invoke.

params - optional arguments to pass to the method.

Returns:

the method return value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the method cannot be found, the invocation fails, or a CLR exception is thrown.

GetOnType

public Object GetOnType(String propertyName)
                 throws JCNativeException

Retrieves a static or type-level property value from the CLR type of the underlying object.

Parameters:

propertyName - the name of the CLR type-level property to read.

Returns:

the property value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the property cannot be found or the read fails.

RegisterEventListener

public void RegisterEventListener(String eventName,
                                  IJCVoidEventEmit eventHandler)
                           throws JCNativeException,
                                  JCException

Registers a void-return CLR event handler on this object.

The handler instance is stored in voidEventMap to prevent premature GC collection while registered. Throws JCException if a handler is already registered for the same event name.

Parameters:

eventName - the CLR event name to subscribe to.

eventHandler - the IJCVoidEventEmit handler to invoke when the event fires.

Throws:

JCNativeException - if the native registration fails.

JCException - if a handler for eventName is already registered.

RegisterEventListener

public void RegisterEventListener(String eventName,
                                  IJCEventEmit eventHandler)
                           throws JCNativeException,
                                  JCException

Registers a value-returning CLR event handler on this object.

The handler instance is stored in eventMap to prevent premature GC collection while registered. Throws JCException if a handler is already registered for the same event name.

Parameters:

eventName - the CLR event name to subscribe to.

eventHandler - the IJCEventEmit handler to invoke when the event fires.

Throws:

JCNativeException - if the native registration fails.

JCException - if a handler for eventName is already registered.

UnregisterEventListener

public void UnregisterEventListener(String eventName,
                                    IJCVoidEventEmit eventHandler)
                             throws JCNativeException,
                                    JCException

Unregisters a void-return CLR event handler from this object.

The handler is removed from voidEventMap, allowing it to be collected by the GC. Throws JCException if no handler is registered for the event name.

Parameters:

eventName - the CLR event name to unsubscribe from.

eventHandler - the IJCVoidEventEmit handler to remove.

Throws:

JCNativeException - if the native unregistration fails.

JCException - if no handler for eventName is registered.

UnregisterEventListener

public void UnregisterEventListener(String eventName,
                                    IJCEventEmit eventHandler)
                             throws JCNativeException,
                                    JCException

Unregisters a value-returning CLR event handler from this object.

The handler is removed from eventMap, allowing it to be collected by the GC. Throws JCException if no handler is registered for the event name.

Parameters:

eventName - the CLR event name to unsubscribe from.

eventHandler - the IJCEventEmit handler to remove.

Throws:

JCNativeException - if the native unregistration fails.

JCException - if no handler for eventName is registered.