Defining Events
Event definitions describe interrupts that the ThingWorx Platform can subscribe to for purposes of receiving notifications when something happens. Events require a Data Shape for event data. Events can be defined directly in code or by using annotations (listed below), but the Data Shape required by the event must be defined in code.
For details about event definitions, Data Shapes for events, and more, click a section title below to display its content:
SteamSensor Data Shapes
The SteamSensor example uses the SteamSensorReadings Data Shape, which is defined below. This code belongs in the constructor or a method called from the constructor. This example is in the public SteamThing(…) constructor:
private void init() throws Exception {
FieldDefinitionCollection fields = new FieldDefinitionCollection();
fields.addFieldDefinition(new FieldDefinition(SENSOR_NAME_FIELD, BaseTypes.STRING));
fields.addFieldDefinition(new FieldDefinition(ACTIVE_TIME_FIELD, BaseTypes.DATETIME));
fields.addFieldDefinition(new FieldDefinition(TEMPERATURE_FIELD, BaseTypes.NUMBER));
fields.addFieldDefinition(new FieldDefinition(PRESSURE_FIELD, BaseTypes.NUMBER));
fields.addFieldDefinition(new FieldDefinition(FAULT_STATUS_FIELD, BaseTypes.BOOLEAN));
fields.addFieldDefinition(new FieldDefinition(INLET_VALVE_FIELD, BaseTypes.BOOLEAN));
fields.addFieldDefinition(new FieldDefinition(TEMPERATURE_LIMIT_FIELD, BaseTypes.NUMBER));
fields.addFieldDefinition(new FieldDefinition(TOTAL_FLOW_FIELD, BaseTypes.INTEGER));
defineDataShapeDefinition("SteamSensorReadings", fields);
}
Collection of Event Definitions
The example below shows how you might add a ThingWorxEventDefinition to a ThingWorxEventDefinitions collection.
@ThingWorxEventDefinitions(events = {
@ThingWorxEventDefinition(
name="ErrorEvent",
description="Event that sends an error",
dataShape="ErrorEventShape",
category="Faults",
isInvocable=true,
isPropertyEvent=false)
}
)
Annotations
Aspects can be set as part of an annotation. Annotations are placed at the beginning of the main code file, after the import statements.You can use the following annotations to define events:
• ThingWorxEventDefinitions — This annotation is a collection of ThingWorxEventDefinition annotations.
• ThingWorxEventDefinition — Defines an event, with the following attributes:
◦ name — Unique identifier of an event.
◦ description — An explanation of the event.
◦ dataShape — The name of the Data Shape that defines the event data.
◦ category — A category name for the event.
◦ isInvocable — A Boolean, indicating whether the event can be invoked from code.
◦ isPropertyEvent — A Boolean, indicating whether the event is associated with a property.
The @ThingWorxEventDefinitions annotation contains all the child @ThingWorxEventDefinition annotations. Annotations are placed at the beginning of the main code file, after the import statements.
Here is an example of defining events from the SteamThing.java example:
@ThingworxEventDefinitions(events = {
@ThingworxEventDefinition(name="SteamSensorFault",description="Steam sensor fault",
dataShape="SteamSensor.Fault", category="Faults", isInvocable=true,
isPropertyEvent=false)
How to Create an Event Definition
To create an event definition, you can call the defineEvent method on the base VirtualThing. There are two defineEvent methods: one that takes an EventDefinition and one that takes the essential parameters for an EventDefinition:
defineEvent(EventDefinition eventDefinition)
defineEvent(String name, String description, String dataShape,
AspectCollection aspects)
The parameters for an event definition are:
• name — The unique identifier for the event.
• description — An explanation of the event.
• dataShape — The name of the Data Shape that defines the event data.
• aspects — The AspectCollection for the event definition.
For example:
super.defineEvent(
"ErrorEvent",
"Event that sends an error",
"ErrorEventShape",
null);
How to Trigger an Event
Triggering an event that the ThingWorx Platform will receive (if subscribed) is straightforward.
 | Just triggering an event is not enough to send it to the ThingWorx Platform. To send an event, you must call the updateSubscribedEvents method of the VirtualThing class. This call sends all events that have been queued to the platform. |
Here is an example from the SteamSensor application, SteamThing.java file:
// Set the event information of the defined data shape for the event
ValueCollection eventInfo = new ValueCollection();
eventInfo.put(CommonPropertyNames.PROP_MESSAGE,
new StringPrimitive("Temperature at " + temperature
+ " was above limit of " + temperatureLimit));
// Queue the event
super.queueEvent("SteamSensorFault", DateTime.now(), eventInfo);