Listening and Processing Events

This section explains how to programmatically list, subscribe to, and process context events.

There are several ways to get a list of events from a Context:

• getEventDefinitions() - this method will return the list of all events in a context
• getEventDefinitions(CallerController caller) - this method will return the list of events accessible by the caller
• getEventDefinitions(String group) - this method will return the list of events belonging to the certain group of its subgroups
• getEventDefinitions(CallerController caller, String group) - this method will return the list of events belonging to the certain group and accessible by the caller

List<EventDefinition> events = context.getEventDefinitions(ContextUtils.GROUP_REMOTE); // Finding all events in group "remote"

To retrieve a single event definition by its name call getEventDefinition(String name) method. The method getEventDefinition(String name, CallerController caller) will return a definition or null if event is not accessible by caller.

Once a certain system component (e.g. a device driver) detects that something has happened, it may fire a context event. The event may be fired asynchronously from any thread. Note, that there is no generic way to fire any event remotely (from Iotellect Client or when using Iotellect Server API).

To fire an event, call Context.fireEvent() method. This method accepts the following parameters:

• Event name
• Event level
• Event parameters (in form of pre-built DataTable or list of its cell values)

Example 1 - firing event by supplying event DataTable:

DataTable eventData = new SimpleDataTable(context.getEventDefinition("myEvent").getFormat()); // Creating empty value
eventData.addRecord().addString("str1").addInt(111); // Adding a record
context.fireEvent("myEvent", EventLevel.INFO, eventData);

Example 2: firing event by supplying event table cell value:

context.fireEvent("randomValue", EventLevel.INFO, new Float(Math.random() * 1000000));

Server modules may subscribe to context events in order to receive and process their instances. In most cases, this functionality is required when implementing custom server plugins.

To subscribe to an event:

• Create an instance of class implementing ContextEventListener interface.
• Pass this instance to Context.addEventListener() method.

ContextEventListener interface has a lot of methods, and in most cases it's more reasonable to inherit your event listener from an existing implementation:

• If writing server-side code (e.g. a plugin), inherit your event listener from ServerEventListener to ensure its correct permission level.
• In other cases, use DefaultContextEventListener as a base.

Using DefaultContextEventListener from code running inside the server JVM will lead to no events being received. This happens because default listener does not incorporate proper permissions.

It's also possible to subscribe to events via ContextManager's void addMaskEventListener(String mask, String event, ContextEventListener listener) method. This way of subscription has a number of differences from subscription via Context interface:

• It's possible to receive events from multiple sources by specifying a mask of contexts
• If subscription was made via ContextManager and a certain context was deleted and then a new context with the same name was created, the same listener will be automatically added to the new context

Most subscription methods have signatures accepting a boolean weak flag. If a certain listener was added as weak, the subscriber will be automatically garbage collected if there are no other strong references to it.

All listeners are non-weak by default.

To speed up event handling fingerprints can be used. Fingerprints allow to match fired event and appropriate listeners more effectively, without traversing over listeners and evaluating their filter expressions. If an event definition has a fingerprint expression it is evaluated when the event is fired. Then listeners with the same fingerprint are directly selected among other fingerprinted listeners. Afterward the rest listeners are traversed in a standard manner.

Once you've subscribed to an event by adding a listener, the system will call listener's handle() method each time when an event occurs. Thus, all processing logic should be added to the implementation of this method:

DefaultContextEventListener listener = new DefaultContextEventListener()
{
@Override
public void handle(Event event) throws EventHandlingException
{
// Handling event here
int level = event.getLevel();
List<Acknowledgement> acknowledgements = event.getAcknowledgements();
// Accessing event data
DataTable eventData = event.getData();
}
};
context.addEventListener("eventName", listener);

There are two ways to access historical events stored in the server database:

• By calling get function from Events context. This method will work both locally (inside server drivers/plugins) and remotely (via server API).
• By calling Server.getDaoFactory().getEventDao().getEvents() Java method. This way is slightly faster than previous one, but it will work inside the server JVM only (e.g. in drivers/plugins).

The get function of Events context returns a Data Table each row of that contains information about one historic event. See its description here.

DataTable history = eventsContext.callFunction(EventsContextConstants.F_GET, getCallerController(), con.getPath(), vd.getName()); // Other parameters omitted

for (DataRecord rec : history)
{
// Process historical events
}

Method of EventDao class that performs loading of events from the database has the following signature:

public Iterator<Event> getEvents(ContextManager cm, CallerController caller, EntityList eventList, EventsFilter filter, Date startDate, Date endDate, Integer maxResults, String sortBy, boolean sortAscending, Object... additionalCriteria) throws DaoException;

This method accept a list of event types to load, pre-filter (additionalCriteria) and post-filter (filter), start/end dates of loaded events occurrence period, maximum number of events to load, and sort options. startDate, endDate and maxResults parameters can be set to null to disable time range and count limit.

It returns an iterator of Event objects representing historical events.

Usage example:

EntityList events = new EntityList("users.admin.devices.my_device", "my_device_event");

Iterator<Event> eventItr = Server.getDaoFactory().getEventDao().getEvents(cm, caller, entities, null, null, null, null, EventDao.EVENT_FIELD_CREATIONTIME, true);

while (eventItr.hasNext())
{
Event ev = eventItr.next();
Date eventTime = ev.getCreationtime();

DataTable eventData = ev.getData();
// Processing
}

Interfaces located in com.tibbo.aggregate.common.server package provide string constants matching names of most server context events and their fields.

Using those constants is always preferred to using string constants defined in your own code. This will ensure error-proof code if some events or fields will get renamed or relocated in the future versions of Iotellect Server.

Was this page helpful?

Tell us more

Send

Thank you!