A wrapper turns the return codes of the C API into the error model of its language: exceptions, error values or results. The rules are in The v4 functions and Exceptions (v4); this page states what a wrapper must tell apart.
Status and exception
- A dxfg_v4_ function returns int32_t: DXFG_EXECUTE_SUCCESSFULLY (0) on success, DXFG_EXECUTE_FAIL (-1) on error. The status is the only error signal: a NULL or 0 written to the out parameter is an ordinary value ("no
session", "no event"), never an error.
- After DXFG_EXECUTE_FAIL, dxfg_v4_get_and_clear_thread_exception() gives the Java exception (its class, message, stack trace and cause) and clears it; release it with dxfg_v4_Exception_release(). The exception belongs to the calling thread, so take it on that thread right after the failed call: a later successful call does not clear an exception that was not taken, and it would be reported for the wrong call.
- Map the exception by its class name: java.lang.IllegalArgumentException (a wrong argument, a NULL out pointer) and java.lang.NullPointerException are errors of the caller, java.lang.IllegalStateException a call in a state that does not allow it, the others failures of the operation. Keep the message and the class in the wrapper's error so that a report names the cause.
- The older functions signal errors in their own ways (a NULL pointer, -1, an exception without a status); a wrapper binds the dxfg_v4_ twins and does not need them.
Outcomes that are not errors
The functions that wait return documented positive codes for the outcomes that are not errors. A wrapper must not treat them as failures, and takes an exception only after DXFG_EXECUTE_FAIL:
A natural mapping makes each outcome its own case: an iterator that ends on DXFG_EVENT_QUEUE_CLOSED, an empty batch for DXFG_EVENT_QUEUE_NO_EVENTS, an exception or an error value for DXFG_EXECUTE_FAIL.
Lost events
Losing events is not an error either: a poll succeeds even when events were dropped before the ones it returns. After a poll, compare dxfg_v4_EventQueue_getDroppedEvents() with its previous value; a larger one means a gap, which the wrapper reports to the application (a counter, a callback, a flag on the batch) as its language allows.