Skip to main content

Event Bus

Overview​

The Beaver IoT platform provides an event bus for communication between various services and integrations within the system. Developers can subscribe to events to implement their business logic. The platform's event bus supports key expression-based event subscriptions for finer-grained subscriptions.

The current platform supports the following event types: Device Events, Entity Events, and Entity Value Data Exchange Events (Exchange). The first two types are generally not sent by developers, as the system automatically sends them when devices or entities are updated. If an integration is interested in these events, it can directly subscribe to the relevant events.

Event Definitions​

Event​

When certain resources in Beaver IoT change, related events Event are triggered. The methods that subscribe to these events are then executed, forming the basis of the system's operation.

Events are classified into: Device Events DeviceEvent, Entity Events EntityEvent, and Entity Value Data Exchange Events ExchangeEvent.

DeviceEvent​

Represents events related to device metadata. The event types (DeviceEvent.EventType) include: Created CREATED, Updated UPDATED, and Deleted DELETED. This event carries the device that has changed. This event is automatically triggered when device metadata is saved, and generally, integration developers do not need to send this event.

The payload for DeviceEvent is a Device object.

EntityEvent​

Represents events related to entity metadata. The event types (EntityEvent.EventType) include: Created CREATED, Updated UPDATED, and Deleted DELETED. This event carries the entity that has changed. This event is automatically triggered when entity metadata is saved, and generally, integration developers do not need to send this event.

The payload for EntityEvent is an Entity object.

ExchangeEvent ​

Represents events related to entity value data. The event types (ExchangeEvent.EventType) include:

  • Service Call CALL_SERVICE
  • Property Update UPDATE_PROPERTY
  • Event Report REPORT_EVENT
  • Custom types defined by other senders

The payload for ExchangeEvent is an ExchangePayload object. If the payload is an annotation-defined entity, the entity class needs to inherit from ExchangePayload.

ExchangeEvent Payload​

ExchangePayload ​

ExchangePayload is the payload for ExchangeEvent, used to carry up and down data for entities. ExchangePayload is widely used in the Beaver IoT platform. It is a Map structure that contains key-value data for Exchange events, where the key is a string and the value is an object. It also contains a context object for carrying additional parameters needed during the Exchange process.

Constructing ExchangePayload​

Constructing a single-value ExchangePayload

ExchangePayload payload = ExchangePayload.create(key, value);
Common Methods for ExchangePayload​
  • Payload-related methods
    // Get value by specified key
    Object getPayload(String key);

    // Get all payloads
    Map<String, Object> getAllPayloads();

    // Get payloads by specified entity type
    Map<String, Object> getPayloadsByEntityType(EntityType entityType);

    // Get corresponding entities
    Map<String, Entity> getExchangeEntities();
  • Context-related methods
    // Get context
    Map<String, Object> getContext();

    // Set context
    void setContext(Map<String, Object> context);

    // Get context by specified key
    Object getContext(String key);

    // Get context by specified key, return default value if not present
    <T> T getContext(String key, T defaultValue);

    // Set context
    void putContext(String key, Object value);
Extending ExchangePayload to Implement Custom Entity Annotation Objects​

In previous sections, we introduced how to build entities based on annotations. In entity definitions, we can extend ExchangePayload to implement custom entity annotation objects, which can receive ExchangePayload data.

  • Example of receiving ExchangePayload data
    @EventSubscribe(payloadKeyExpression = "my-integration.integration.*")
    public void onAddDevice(Event<MyIntegrationEntities> event) {
        MyIntegrationEntities myIntegrationEntities = event.getPayload();
        // Can also get sub-entity objects
        String ip = myIntegrationEntities.getAddDevice().getIp();
        ...
    }

Entity ExchangePayload Event Publishing ​

The Beaver IoT platform provides an ExchangePayload event publishing executor, enabling developers to publish entity ExchangeEvent events by invoking methods from the EntityValueServiceProvider service or the relevant methods of the entity's Wrapper. Both synchronous and asynchronous publishing methods are supported.

  • Synchronous event publishing methods typically end with Sync, such as EntityValueServiceProvider.saveValuesAndPublishSync and AnnotatedEntityWrapper.publishSync.
  • Asynchronous event publishing methods typically end with Async, such as saveValuesAndPublishAsync and AnnotatedEntityWrapper.publishAsync.

Event Publishing Process​

ExchangeEvent events trigger a general built-in process that includes data validation, current value saving (for property entities), and historical value saving before triggering the related subscription methods.

Exchange Event Flow

Whether it is a synchronous or asynchronous request, the relevant listeners will be called.

For synchronous requests, if any listener throws an exception, the exception will be caught and collected, and then an exception will be thrown after all synchronous listeners have been executed. If no exception is thrown, the results of all synchronous listeners will be returned.

info

The Beaver IoT platform supports returning responses for synchronous calls and executing multiple listeners, returning an EventResponse response object.

Event Subscription​

The platform provides the @EventSubscribe annotation for subscribing to events. The currently supported event types are Device Events, Entity Events, and Entity Value Data Exchange Events (Exchange). Wildcard expressions are also supported for key matching.

Annotation Description​

  • @EventSubscribe annotation
    • eventType: Event type, refer to the event definitions section.
    • payloadKeyExpression: Key expression for matching the event's payload object, supports wildcards, e.g., my-integration.* matches all keys starting with my-integration.

Event Subscription​

Subscribe to ExchangeEvent​

@Service
public class MyDeviceService {
    
    @EventSubscribe(payloadKeyExpression = "my-integration.integration.add_device.*", eventType = ExchangeEvent.EventType.CALL_SERVICE)
    public void onServiceCall(Event<MyIntegrationEntities.ServiceEntity> event) {
        MyIntegrationEntities.ServiceEntity serviceEntity = event.getPayload();  // Entity annotated object can be used as a parameter to receive ExchangePayload requests
        // ...
    }

    @EventSubscribe(payloadKeyExpression = "my-integration.integration.xxxx", eventType = {ExchangeEvent.EventType.CALL_SERVICE, ExchangeEvent.EventType.UPDATE_PROPERTY})
    public EventResponse onMultiEventType(ExchangeEvent event) {
        Object ctxValue = event.getPayload().getContext("<Something in context>");
        // Synchronously return response status
        return EventResponse.of("<responseKey>", "<responseValue>");
    }
}
info
  • Entity annotated objects can be used as parameters to receive ExchangePayload requests, such as: MyIntegrationEntities.ServiceEntity.
  • The @EventSubscribe annotation subscribes to events, where eventType denotes the event type, which is optional and can include multiple values. If left empty, it subscribes to all event types.
  • The Beaver IoT platform executes asynchronously for asynchronous subscriptions and synchronously for synchronous subscriptions. Developers can add the @Async annotation to execute asynchronously, achieving business asynchronous thread pool isolation.

Subscribing to DeviceEvent Events​

@Service
public class MyDeviceService {
    
    @EventSubscribe(payloadKeyExpression = "my-integration.device.*", eventType = DeviceEvent.EventType.CREATED)
    public void onSaveDevice(DeviceEvent event) {
        ...
    }
}
tip

The Beaver IoT platform exposes events for adding, deleting, and updating devices. Developers can subscribe to these events to implement their business logic. Generally, developers do not need to focus on these events.

Subscribing to EntityEvent Events​

@Service
public class MyEntityService {
    
    @EventSubscribe(payloadKeyExpression = "my-integration.device.*", eventType = DeviceEvent.EventType.CREATED)
    public void onSaveEntity(EntityEvent event) {
        ...
    }
}
tip

The Beaver IoT platform exposes events for adding, deleting, and updating entities. Developers can subscribe to these events to implement their business logic. Generally, developers do not need to focus on these events.