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 or raiseEventConcurrent 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.Two concurrency models are available:
raiseEvent overloads serialize all calls at the instance
level. Safe for all scenarios but may become a bottleneck when multiple events are
raised concurrently. State is stored in eventData, returnData, and
extraData and accessed via the no-argument accessors.raiseEventConcurrent overloads allow different events to
proceed in parallel. Each invocation is assigned a unique callId generated by
nextCallId(). State is tracked per callId in _eventData,
_returnData, and _extraData. The CLR handler reads event data via
getEventData(long) and sets the return value via
setReturnData(long, Object); the return value is delivered directly as the
return value of raiseEventConcurrent. If _forceSynchronized is
true, concurrent calls fall back to the synchronized model.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.
|
Object[] |
extraData(long callId)
Returns the additional arguments associated with the call identified by
callId. |
int |
extraDataLength()
Returns the number of additional arguments associated with the current event.
|
int |
extraDataLength(long callId)
Returns the number of additional arguments associated with the call identified by
callId. |
long |
getCollisionCount()
Returns the number of ring buffer slot collisions detected since the JVM started.
|
Object |
getEventData()
Returns the primary data object associated with the current event.
|
Object |
getEventData(long callId)
Returns the primary data object associated with the given call identifier.
|
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.
|
Object |
getReturnData(long callId)
Returns the return value set by the CLR handler with the call identified by
callId. |
boolean |
hasExtraData()
Returns
true if the current event has additional arguments beyond the primary
data object. |
boolean |
hasExtraData(long callId)
Returns
true if the call identified by callId has additional arguments
beyond the primary data object. |
void |
initRingSize(int ringSize)
Initializes the ring buffer size for this listener instance.
|
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.
|
Object |
raiseEventConcurrent(int eventIndex)
Raises the event identified by numeric index on the CLR side with no associated data.
|
Object |
raiseEventConcurrent(int eventIndex,
Object e)
Raises the event identified by numeric index on the CLR side, passing a single data object.
|
Object |
raiseEventConcurrent(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.
|
Object |
raiseEventConcurrent(String eventName)
Raises the event identified by numeric index on the CLR side with no associated data.
|
Object |
raiseEventConcurrent(String eventName,
Object e)
Raises the event identified by numeric index on the CLR side, passing a single data object.
|
Object |
raiseEventConcurrent(String eventName,
Object e,
Object... objects)
Raises the event identified by numeric index 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 |
setEmitCollisionWarnings(boolean emitWarnings)
Sets whether collision warnings are emitted to stderr when a ring buffer slot collision
is detected.
|
void |
setReturnData(long callId,
Object retData)
Sets the return value that the CLR handler provides for the call identified by
callId. |
void |
setReturnData(Object retData)
Sets the return value that the CLR handler provides for the current event.
|
void |
setSynchronized(boolean forceSynchronized)
Forces all
raiseEventConcurrent calls to fall back to the synchronized model. |
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 setSynchronized(boolean forceSynchronized)
raiseEventConcurrent calls to fall back to the synchronized model.setSynchronized in interface IJCListenerforceSynchronized - true to force synchronized execution.public void setEmitCollisionWarnings(boolean emitWarnings)
true. Set to false to suppress warnings in
production environments where collisions are expected and monitored via getCollisionCount().setEmitCollisionWarnings in interface IJCListeneremitWarnings - true to enable warnings, false to suppress them.public void initRingSize(int ringSize)
initRingSize in interface IJCListenerringSize - the desired ring buffer size; will be rounded up to the next power of two.public long getCollisionCount()
JCOBRIDGE_ListenerRingSize should be increased.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 or raiseEventConcurrent 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)
raiseEvent in interface IJCListenereventName - the name of the event to raise.public void raiseEvent(int eventIndex)
raiseEvent in interface IJCListenereventIndex - the numeric index of the event to raise, as returned by
getEventIndex(String).public void raiseEvent(String eventName, Object e)
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)
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)
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)
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 raiseEventConcurrent(String eventName)
setReturnData(long, Object), or null for void events.
If _forceSynchronized is true, falls back to raiseEvent(int)
and returns getReturnData().
raiseEventConcurrent in interface IJCListenereventName - the name of the event to raise.null.public Object raiseEventConcurrent(int eventIndex)
setReturnData(long, Object), or null for void events.
If _forceSynchronized is true, falls back to raiseEvent(int)
and returns getReturnData().
raiseEventConcurrent in interface IJCListenereventIndex - the numeric index of the event to raise, as returned by
getEventIndex(String).null.public Object raiseEventConcurrent(String eventName, Object e)
getEventData(long). Returns the value set by the CLR handler via
setReturnData(long, Object), or null for void events.
If _forceSynchronized is true, falls back to
raiseEvent(int, Object) and returns getReturnData().
raiseEventConcurrent in interface IJCListenereventName - the name of the event to raise.e - the data object associated with the event.null.public Object raiseEventConcurrent(int eventIndex, Object e)
getEventData(long). Returns the value set by the CLR handler via
setReturnData(long, Object), or null for void events.
If _forceSynchronized is true, falls back to
raiseEvent(int, Object) and returns getReturnData().
raiseEventConcurrent in interface IJCListenereventIndex - the numeric index of the event to raise.e - the data object associated with the event.null.public Object raiseEventConcurrent(String eventName, Object e, Object... objects)
setReturnData(long, Object), or null for void events.
If _forceSynchronized is true, falls back to
raiseEvent(int, Object, Object...) and returns getReturnData().
raiseEventConcurrent 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(long).null.public Object raiseEventConcurrent(int eventIndex, Object e, Object... objects)
setReturnData(long, Object), or null for void events.
If _forceSynchronized is true, falls back to
raiseEvent(int, Object, Object...) and returns getReturnData().
raiseEventConcurrent 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(long).null.public Object getEventData()
raiseEvent overloads.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. For use with the synchronized raiseEvent overloads.hasExtraData in interface IJCListenertrue if extra data is available.public int extraDataLength()
raiseEvent overloads.extraDataLength in interface IJCListener0 if none.public Object[] extraData()
raiseEvent overloads.extraData in interface IJCListenernull if none was provided.public Object getReturnData()
raiseEvent overloads.getReturnData in interface IJCListenernull if not set.public void setReturnData(Object retData)
raiseEvent overloads.setReturnData in interface IJCListenerretData - the value to return to the JVM caller.public Object getEventData(long callId)
raiseEventConcurrent.getEventData in interface IJCListenercallId - the unique call identifier generated by raiseEventConcurrent.null if no data was provided.public boolean hasExtraData(long callId)
true if the call identified by callId has additional arguments
beyond the primary data object.
Called by the CLR runtime to decide whether to fetch extra data.hasExtraData in interface IJCListenercallId - the unique call identifier generated by raiseEventConcurrent.true if extra data is available.public int extraDataLength(long callId)
callId.extraDataLength in interface IJCListenercallId - the unique call identifier generated by raiseEventConcurrent.0 if none.public Object[] extraData(long callId)
callId.extraData in interface IJCListenercallId - the unique call identifier generated by raiseEventConcurrent.null if none was provided.public Object getReturnData(long callId)
callId.
Used from CLR since the value is returned directly by raiseEventConcurrent.getReturnData in interface IJCListenercallId - the unique call identifier generated by raiseEventConcurrent.null if not set.public void setReturnData(long callId,
Object retData)
callId. The value is returned directly by raiseEventConcurrent.setReturnData in interface IJCListenercallId - the unique call identifier generated by raiseEventConcurrent.retData - the value to return to the JVM caller.