public class JCListener extends Object implements IJCListener
Subclass this class and implement the Java interface of interest. Each interface method
must call one of the raiseEvent overloads to transfer control to the CLR side.
The CLR counterpart (a subclass of JVMBridgeListener) registers handlers that are
invoked when raiseEvent crosses the JNI boundary.
Event identification supports two modes:
String. The name is resolved to
a numeric index on the first call and the index is cached in _listenerKey.getEventIndex(String)
directly. This avoids the name-lookup overhead on every invocation and is the preferred
approach in high-frequency scenarios.For non-void interface methods, the CLR handler must call
setReturnData(Object) before returning. The JVM implementation then retrieves
the value via getReturnData() and returns it to the original Java caller.
Example — implementing ActionListener:
public final class JCActionListener extends JCListener implements ActionListener {
public JCActionListener(String key) throws JCNativeException {
super(key);
}
public void actionPerformed(ActionEvent e) {
raiseEvent("actionPerformed", e);
}
}
| Constructor and Description |
|---|
JCListener(String key)
Constructs a
JCListener and registers it with the JCOBridge native runtime
using the provided key. |
| Modifier and Type | Method and Description |
|---|---|
Object[] |
extraData()
Returns the additional arguments associated with the current event.
|
int |
extraDataLength()
Returns the number of additional arguments associated with the current event.
|
Object |
getEventData()
Returns the primary data object associated with the current event.
|
int |
getEventIndex(String eventName)
Returns the numeric index associated with the given event name.
|
Object |
getReturnData()
Returns the return value set by the CLR handler for the current event.
|
boolean |
hasExtraData()
Returns
true if the current event has additional arguments beyond the primary
data object. |
void |
raiseEvent(int eventIndex)
Raises the event identified by numeric index on the CLR side with no associated data.
|
void |
raiseEvent(int eventIndex,
Object e)
Raises the event identified by numeric index on the CLR side, passing a single data object.
|
void |
raiseEvent(int eventIndex,
Object e,
Object... objects)
Raises the event identified by numeric index on the CLR side, passing a primary data object
and additional arguments.
|
void |
raiseEvent(String eventName)
Raises the named event on the CLR side with no associated data.
|
void |
raiseEvent(String eventName,
Object e)
Raises the named event on the CLR side, passing a single data object.
|
void |
raiseEvent(String eventName,
Object e,
Object... objects)
Raises the named event on the CLR side, passing a primary data object and additional arguments.
|
void |
release()
Releases the native resources held by this listener and unregisters it from the
JCOBridge runtime.
|
void |
setReturnData(Object retData)
Sets the return value that the CLR handler provides for the current event.
|
public JCListener(String key) throws JCNativeException
JCListener and registers it with the JCOBridge native runtime
using the provided key.key - the registration key that uniquely identifies this listener instance
and links it to its CLR counterpart.JCNativeException - if the native bridge initialization fails.public void release()
release in interface IJCListenerpublic int getEventIndex(String eventName)
The listener handle (_listenerKey) is resolved lazily on the first call
and cached for subsequent calls. The returned index can be passed to the
index-based raiseEvent overloads to avoid name-lookup overhead in
high-frequency event paths.
getEventIndex in interface IJCListenereventName - the name of the event as registered on the CLR side.0 if the lookup fails.public void raiseEvent(String eventName)
eventData, returnData, and extraData are cleared
before the native call and eventData is cleared again in the finally block
to ensure no stale reference is held after the call returns.
raiseEvent in interface IJCListenereventName - the name of the event to raise.public void raiseEvent(int eventIndex)
The listener handle (_listenerKey) is resolved lazily on the first call.
Prefer this overload over the name-based variant in high-frequency paths.
raiseEvent in interface IJCListenereventIndex - the numeric index of the event to raise, as returned by
getEventIndex(String).public void raiseEvent(String eventName, Object e)
The data object e is stored in eventData before the native call
so that the CLR runtime can retrieve it via getEventData(). It is cleared
in the finally block after the call returns.
raiseEvent in interface IJCListenereventName - the name of the event to raise.e - the data object associated with the event; accessible from the CLR
handler via getEventData().public void raiseEvent(int eventIndex,
Object e)
Prefer this overload over the name-based variant in high-frequency paths.
The listener handle (_listenerKey) is resolved lazily on the first call.
raiseEvent in interface IJCListenereventIndex - the numeric index of the event to raise.e - the data object associated with the event; accessible from the CLR
handler via getEventData().public void raiseEvent(String eventName, Object e, Object... objects)
Note: this overload is not synchronized to avoid deadlocks when the caller
already holds a monitor. extraData is stored before the native call and remains
accessible from the CLR handler via extraData().
raiseEvent in interface IJCListenereventName - the name of the event to raise.e - the primary data object associated with the event.objects - additional arguments forwarded to the CLR handler, accessible via
extraData().public void raiseEvent(int eventIndex,
Object e,
Object... objects)
Note: this overload is not synchronized — see
raiseEvent(String, Object, Object...) for the rationale.
The listener handle (_listenerKey) is resolved lazily on the first call.
raiseEvent in interface IJCListenereventIndex - the numeric index of the event to raise.e - the primary data object associated with the event.objects - additional arguments forwarded to the CLR handler, accessible via
extraData().public Object getEventData()
raiseEvent.getEventData in interface IJCListenernull if no data was provided.public boolean hasExtraData()
true if the current event has additional arguments beyond the primary
data object. Called by the CLR runtime to decide whether to fetch extra data.hasExtraData in interface IJCListenertrue if extraData is non-null and non-empty.public int extraDataLength()
0 if hasExtraData() is false.extraDataLength in interface IJCListener0 if none.public Object[] extraData()
objects vararg passed to
raiseEvent.extraData in interface IJCListenernull if none was provided.public Object getReturnData()
For non-void Java interface methods, the CLR handler must call
setReturnData(Object) before returning control to the JVM. The JVM
implementation then calls this method to retrieve the value and return it to the
original Java caller.
getReturnData in interface IJCListenernull if not set.public void setReturnData(Object retData)
Must be called by the CLR runtime before control returns to the JVM for non-void
interface methods. The value is then retrieved by the JVM implementation via
getReturnData() and returned to the original Java caller.
setReturnData in interface IJCListenerretData - the value to return to the JVM caller; may be null for
reference types if the interface method allows it.