Defining and Implementing Events

When defining your own device/agent/server context events, it's necessary to specify properties of their definitions, i.e. name, description, format, help text, permission level, and group. To declare new event, create an instance of EventDefinition object and set its properties. Here is an example:

// Creating event data format (scalar, string)
FieldFormat ff = FieldFormat.create("demoEventField", FieldFormat.STRING_FIELD);
TableFormat format = new TableFormat(1, 1, ff);

// Creating event definition
EventDefinition ed = new EventDefinition("demoEvent", format, "Demo Event", ContextUtils.GROUP_DEFAULT);

Once done, add the event definition to a context:

  • Definitions of device driver context's events matching device events should be returned by overridden DeviceDriver.readEventDefinitions() method.
  • Server plugins should add events from inside install() and start() methods.
  • Java-based Agents should add events after Agent object creation via Agent.getContext().addEventDefinition().
  • Finally, scripts (both server and widget scripts) should not normally add any events.

For server-side events, it might be also necessary to specify their expiration period and permission level:

// Setting permission level
ed.setPermissions(ServerPermissionChecker.getManagerPermissions());

Device events provided by a device driver, along with Agent events, must belong to a group remote.

Event group is specified by calling EventDefinition.setGroup().

You can use the following syntax:

ed.setGroup(ContextUtils.GROUP_REMOTE);

Event Generation

Plugins, drivers and Agents may generate context events using fireEvent() method of Context interface. Here is an example:

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

Format of data table passed to fireEvent() method must match format contained in event definition. Failure to follow this rule may result in data loss since the system will try convert the data table to definition-provided format preserving as much data as it can.

Was this page helpful?