Skip to main content

API Reference

Overview​

The Beaver IoT platform provides a series of general service interfaces for integration developers, supporting multiple business scenarios such as devices, templates, blueprints, credentials, MQTT, and more.

DeviceServiceProvider Interface Documentation​

DeviceServiceProvider provides common device operation methods.

save ​

Save a device (including entities under the device)

void save(Device device);

deleteById​

Delete a device by device ID

void deleteById(Long id);

findById​

Find a device by device ID

Device findById(Long id);

findByKey​

Find a device by device key

Device findByKey(String deviceKey);

findByKeys​

Find devices by a list of device keys

List<Device> findByKeys(List<String> deviceKey);

findByIdentifier​

Find a device by identifier and integration ID

Device findByIdentifier(String identifier, String integrationId);

findByIdentifiers​

Find devices by a list of identifiers and integration ID

List<Device> findByIdentifiers(List<String> identifier, String integrationId);

findAll​

Find all devices by integration ID

List<Device> findAll(String integrationId);

countByDeviceTemplateKey​

Count devices by device template key

long countByDeviceTemplateKey(String deviceTemplateKey);

deleteByDeviceTemplateKey​

Delete devices by device template key

void deleteByDeviceTemplateKey(String deviceTemplateKey);

clearTemplate​

Clear template content under the specified device template key

void clearTemplate(String deviceTemplateKey);

DeviceStatusServiceProvider Interface Documentation​

DeviceStatusServiceProvider provides device online/offline status management.

register​

Register integration to the device status manager

void register(String integrationId, DeviceStatusConfig config);

online​

Set device status to "online"

void online(Device device);

offline​

Set device status to "offline"

void offline(Device device);

status​

Get the current status of a device

DeviceStatus status(Device device);

DeviceTemplateServiceProvider Interface Documentation​

DeviceTemplateServiceProvider provides management operations for device templates.

save​

Save a device template

void save(DeviceTemplate deviceTemplate);

deleteById​

Delete a device template by ID

void deleteById(Long id);

deleteByKey​

Delete a device template by key

void deleteByKey(String key);

findById​

Find a device template by ID

DeviceTemplate findById(Long id);

findByIds​

Find device templates by a list of IDs

List<DeviceTemplate> findByIds(List<Long> ids);

findByKey​

Find a device template by key

DeviceTemplate findByKey(String deviceTemplateKey);

findByKeys​

Find device templates by a list of keys

List<DeviceTemplate> findByKeys(List<String> deviceTemplateKey);

findByIdentifier​

Find a device template by identifier and integration ID

DeviceTemplate findByIdentifier(String identifier, String integrationId);

findByIdentifiers​

Find device templates by a list of identifiers and integration ID

List<DeviceTemplate> findByIdentifiers(List<String> identifier, String integrationId);

findAll​

Find all device templates by integration ID

List<DeviceTemplate> findAll(String integrationId);

findAllCustom​

Find all custom device templates by integration ID

List<DeviceTemplate> findAllCustom(String integrationId);

batchDelete​

Batch delete device templates

void batchDelete(List<Long> ids);

Paginated search for device templates

Page<DeviceTemplateResponseData> search(SearchDeviceTemplateRequest searchDeviceTemplateRequest);

DeviceTemplateParserProvider Interface Documentation​

DeviceTemplateParserProvider provides parsing and validation for device template content.

validate​

Validate the format of template content

boolean validate(String deviceTemplateContent);

defaultContent​

Get the default template content

String defaultContent();

parse​

Parse template content

DeviceTemplateModel parse(String deviceTemplateContent);

input​

Process input data using the template (multiple overloads)

DeviceTemplateInputResult input(String integration, Long deviceTemplateId, Object data);
DeviceTemplateInputResult input(String integration, Long deviceTemplateId, String deviceIdentifier, String deviceName, Object data);
DeviceTemplateInputResult input(String integration, Long deviceTemplateId, Object data, Map<String, Object> codecArgContext);
DeviceTemplateInputResult input(String integration, Long deviceTemplateId, String deviceIdentifier, String deviceName, Object data, Map<String, Object> codecArgContext);
DeviceTemplateInputResult input(String deviceKey, Object data, Map<String, Object> codecArgContext);

output​

Process output data using the template (multiple overloads)

DeviceTemplateOutputResult output(String deviceKey, ExchangePayload payload);
DeviceTemplateOutputResult output(String deviceKey, ExchangePayload payload, Map<String, Object> codecArgContext);

createDevice​

Create a device using the template (multiple overloads)

Device createDevice(String integration, Long deviceTemplateId, String deviceId, String deviceName);
Device createDevice(String integration, String vendor, String model, String deviceIdentifier, String deviceName, BiFunction<Device, Map<String, Object>, Boolean> beforeSaveDevice, BlueprintCreationStrategy strategy);
Device createDevice(String integration, String vendor, String model, String deviceIdentifier, String deviceName, BiFunction<Device, Map<String, Object>, Boolean> beforeSaveDevice);

getLatestDeviceTemplate​

Get the latest device template

DeviceTemplate getLatestDeviceTemplate(String vendor, String model);

DeviceBlueprintMappingServiceProvider Interface Documentation​

DeviceBlueprintMappingServiceProvider provides mapping between device IDs and blueprint IDs.

getBlueprintIdByDeviceIds​

Get blueprint ID mappings by a list of device IDs

List<DeviceBlueprintMappingDTO> getBlueprintIdByDeviceIds(List<Long> deviceIdList);

BlueprintLibraryResourceResolverProvider Interface Documentation​

BlueprintLibraryResourceResolverProvider provides access to blueprint library resources.

getDeviceVendors​

Get all device vendors

List<BlueprintDeviceVendor> getDeviceVendors();

getDeviceVendor​

Get vendor information by vendor ID

BlueprintDeviceVendor getDeviceVendor(String vendorId);

getDeviceModels​

Get all device models under the specified vendor

List<BlueprintDeviceModel> getDeviceModels(String vendorId);

getDeviceModel​

Get device model information by vendor ID and model ID

BlueprintDeviceModel getDeviceModel(String vendorId, String modelId);

getDeviceTemplateContent​

Get device template content by vendor ID and model ID

String getDeviceTemplateContent(String vendorId, String modelId);

BlueprintLibrarySyncerProvider Interface Documentation​

BlueprintLibrarySyncerProvider provides blueprint library change listening capability.

addListener​

Add a blueprint library change listener

void addListener(Consumer<BlueprintLibrary> listener);

CredentialsServiceProvider Interface Documentation​

CredentialsServiceProvider provides credential management capabilities.

addCredentials​

Add credentials

void addCredentials(Credentials credentials);

batchDeleteCredentials​

Batch delete credentials

void batchDeleteCredentials(List<Long> ids);

getCredentials​

Get credentials by credential type or ID

Optional<Credentials> getCredentials(String credentialType);
Optional<Credentials> getCredentials(CredentialsType credentialType);
Optional<Credentials> getCredentials(Long id);
Optional<Credentials> getCredentials(String credentialType, String accessKey);
Optional<Credentials> getCredentials(CredentialsType credentialType, String accessKey);

getOrCreateCredentials​

Get or create credentials (multiple overloads)

Credentials getOrCreateCredentials(String credentialType);
Credentials getOrCreateCredentials(String credentialType, String password);
Credentials getOrCreateCredentials(CredentialsType credentialType);
Credentials getOrCreateCredentials(CredentialsType credentialType, String password);
Credentials getOrCreateCredentials(String credentialType, String username, String password);
Credentials getOrCreateCredentials(CredentialsType credentialType, String username, String password);

EntityServiceProvider Interface Documentation​

EntityServiceProvider provides entity management capabilities.

findByTargetId ​

Get a list of entities by target type and target ID

info

Target types include Device (AttachTargetType.DEVICE) and Integration (AttachTargetType.INTEGRATION)

@NonNull List<Entity> findByTargetId(AttachTargetType targetType, String targetId);

findByTargetIds​

Get a list of entities by target type and a list of target IDs

@NonNull List<Entity> findByTargetIds(AttachTargetType targetType, List<String> targetIds);

save ​

Save an entity

void save(Entity entity);

batchSave​

Batch save entities

void batchSave(List<Entity> entityList);

deleteByTargetId​

Delete entities by target ID

void deleteByTargetId(String targetId);

deleteByKey​

Delete an entity by entity key

void deleteByKey(String entityKey);

findByKey​

Find an entity by entity key

Entity findByKey(String entityKey);

findByKeys​

Find entities by a collection of entity keys

Map<String, Entity> findByKeys(Collection<String> entityKeys);

findById​

Find an entity by entity ID

Entity findById(Long entityId);

findByIds​

Find entities by a list of entity IDs

List<Entity> findByIds(List<Long> ids);

findTagsByIds​

Find tags by a list of entity IDs

Map<Long, List<EntityTag>> findTagsByIds(List<Long> entityIds);

EntityTemplateServiceProvider Interface Documentation​

EntityTemplateServiceProvider provides entity template management capabilities.

findAll​

Get all entity templates

List<EntityTemplate> findAll();

findByKeys​

Get entity templates by a list of keys

List<EntityTemplate> findByKeys(List<String> keys);

findByKey​

Get an entity template by key

EntityTemplate findByKey(String key);

EntityValueServiceProvider Interface Documentation​

EntityValueServiceProvider provides reading/writing of entity values and event publishing.

saveValuesAndPublishSync​

Save entity values and synchronously publish events

  • Default event type:
EventResponse saveValuesAndPublishSync(ExchangePayload exchangePayload);
  • Specified event type:
EventResponse saveValuesAndPublishSync(ExchangePayload exchangePayload, String eventType);

saveValuesAndPublishAsync​

Save entity values and asynchronously publish events

  • Default event type:
void saveValuesAndPublishAsync(ExchangePayload exchangePayload);
  • Specified event type:
void saveValuesAndPublishAsync(ExchangePayload exchangePayload, String eventType);

saveLatestValues​

Save the latest entity values

void saveLatestValues(ExchangePayload exchangePayload);

saveValues​

Save entity values (with specified timestamp)

void saveValues(ExchangePayload exchangePayload, long timestamp);

saveValues​

Save entity values (current time)

void saveValues(ExchangePayload exchangePayload);

saveHistoryRecord​

Save entity historical values (with specified timestamp)

void saveHistoryRecord(Map<String, Object> recordValues, long timestamp);

saveHistoryRecord​

Save entity historical values (current time)

void saveHistoryRecord(Map<String, Object> recordValues);

mergeHistoryRecord​

Merge entity historical values (with specified timestamp)

void mergeHistoryRecord(Map<String, Object> recordValues, long timestamp);

existHistoryRecord​

Check if entity historical records exist

  • Multiple key check:
Set<String> existHistoryRecord(Set<String> keys, long timestamp);
  • Single key check:
boolean existHistoryRecord(String key, long timestamp);

findValueByKey​

Find the current value by entity key

Object findValueByKey(String key);

findValuesByKeys​

Find current values by a list of entity keys

Map<String, Object> findValuesByKeys(List<String> keys);

findValuesByKey​

Find current values of child entities under the parent entity by entity key and type

@NonNull <T extends ExchangePayload> T findValuesByKey(String key, Class<T> entitiesClazz);

IntegrationServiceProvider Abstract Class Documentation​

IntegrationServiceProvider abstract class defines integration-related operations.

save​

Save an integration (including entities under the integration)

void save(Integration integrationConfig);

batchSave​

Batch save integrations

void batchSave(Collection<Integration> integrationConfig);

getIntegration​

Get an integration instance by integration ID (including disabled ones)

Integration getIntegration(String integrationId);

getActiveIntegration​

Get the enabled integration instance by integration ID

Integration getActiveIntegration(String integrationId);

findIntegrations​

Find all integrations

Collection<Integration> findIntegrations();

findVisibleIntegrations​

Find all visible integrations

List<Integration> findVisibleIntegrations();

findActiveIntegrations​

Find all enabled integrations

List<Integration> findActiveIntegrations();

findIntegrations (with condition)​

Find integrations by condition

List<Integration> findIntegrations(Predicate<Integration> predicate);

Example: Find all integrations that can add devices

List<Integration> integrations = integrationServiceProvider.findIntegrations(f -> StringUtils.hasText(f.getEntityKeyAddDevice()));

MqttPubSubServiceProvider Interface Documentation​

MqttPubSubServiceProvider provides MQTT message publishing and subscription capabilities.

publish​

Publish message to specified topic

  • Specify username
void publish(String username, String topicSubPath, byte[] payload, MqttQos qos, boolean retained);
  • Specify tenant
void publish(String topicSubPath, byte[] payload, MqttQos qos, boolean retained);

subscribe​

Subscribe to messages of specified topic

  • Specify username and shared mode
void subscribe(String username, String topicSubPath, MqttMessageListener onMessage, boolean shared);
  • Specify tenant and shared mode
void subscribe(String topicSubPath, MqttMessageListener onMessage, boolean shared);
  • Specify username
void subscribe(String username, String topicSubPath, MqttMessageListener onMessage);
  • Specify tenant
void subscribe(String topicSubPath, MqttMessageListener onMessage);

unsubscribe​

Unsubscribe

  • Specify listener
void unsubscribe(MqttPubSubServiceListener onMessage);
  • Specify username and topic
void unsubscribe(String username, String topicSubPath);
  • Specify topic
void unsubscribe(String topicSubPath);

onConnect​

MQTT connection event listener

void onConnect(MqttConnectEventListener listener);

onDisconnect​

MQTT disconnection event listener

void onDisconnect(MqttDisconnectEventListener listener);

getFullTopicName​

Get the full topic name

  • Specify username
String getFullTopicName(String username, String topicSubPath);
  • Specify tenant
String getFullTopicName(String topicSubPath);

getMqttBrokerInfo​

Get MQTT Broker information

MqttBrokerInfo getMqttBrokerInfo();