Event Module¶
Contents
Description¶
The Event module allows to create a listener, that contains an action, triggered by firing an event. The module is using
MotechEvent
to provide event with specific data that can be sent by any MOTECH module (using EventRelay
) when an event is fired.
The module is using ActiveMQ for delivery of the events. It is possible to register your own callback
function using EventCallbackService
.
MotechEvent¶
The Event module uses MotechEvent
to store information about fired event. Instance of this class can be sent by
any module to a specific handler to fire an event. Every module can also be a subscriber of an event and receive events to handle.
Main fields of MotechEvent
:
Field | Description | Type |
---|---|---|
subject | Identifies event. The listeners can subscribe event using it. | String |
messageDestination | Destination of an event. Contains the id of the Motech listener that this event is meant for. | String |
callbackName | Name of service, which is containing callback functions. | String |
parameters | Parameters of event. Contains data used in event execution. | Map<String, Object> |
metadata | Stores any additional data, that is not meant to be the event’s payload. | Map<String, Object> |
This class is immutable.
Listener¶
There are 2 ways to create an event listener:
Use an
@MotechListener
annotation to a handler function.In Core Architecture you can find an example usage of this annotation.
Use an OSGi
EventListenerRegistry
service exposed by the event module.
Register custom callback¶
ActiveMQ is sending events with its own retry. The default ActiveMQ retries will take place when the handler method fails (an exception is thrown).
The default retries can be disabled by custom event callback service (flag returned by the failureCallback method). To register
event callbacks you should implement an EventCallbackService
interface and expose it as OSGi service. Then this service
name must be set in the callback field of the MotechEvent
.
Example of a custom callback¶
First you should implement an EventCallbackService
:
@Service('serviceName') public class ServiceName implements EventCallbackService { public static final String CALLBACK_NAME = "CallbackName"; @Override public boolean failureCallback(MotechEvent event, Throwable throwable) { //Actions for failure } @Override public void successCallback(MotechEvent event) { //Actions for success } @Override public String getName() { return CALLBACK_NAME; } }
Then expose it as the OSGi service:
<osgi:service id="serviceId" auto-export="interfaces" ref="serviceName" interface="org.motechproject.event.listener.EventCallbackService"/>
After that you can use a callback service in MotechEvent
by using e.g. such construction:
eventRelay.sendEventMessage(new MotechEvent(eventSubject, parameters, ServiceName.CALLBACK_NAME, metadata));