Things-client 3.0 - deprecated
Client
things-client 3.0.0 - deprecated
Major release, breaking cr-integration-client 2.4.1 (deprecated)
Highlights
- New Maven coordinates:
<groupId>com.bosch.iot.things.client
</groupId>
<artifactId>things-client
</artifactId> - Two channels to communicate to the “Bosch IoT Things”
backend
- Twin - This is the new name for the old channel, e.g. command from client to the Things backend, and response back.
- Live - The new live channel allows client to client communication
- The live channel can be employed for using the same API of the Things Client in order to update/retrieve values to “live” devices and for sending/consuming messages to/from “live” devices
- An API was added for handling live commands and responding to them the way the Things protocol defines commands/responses and events.
Find a schematic view on the twin and live channel at
Bosch IoT Things Protocol.
See as well section things-client-api 3.0.0.
Breaking Changes
- The new entry point for instantiating a Things client is the
ThingsClientFactory
.
Via the factory you can also instantiate theTwinConfiguration
and theLiveConfiguration
. - The
IntegrationClient
was renamed toThingsClient
- The
IntegrationClientConfiguration
class was removed.
Please use instead theTwinConfiguration
, theLiveConfiguration
, or both. - The
IntegrationClientImpl
class is not public anymore, but for internal use only.- The
IntegrationClientImpl#newInstance()
methods were removed. - Please use the
ThingsClientFactory
class instead.
- The
- The
TwinConfiguration
and theLiveConfiguration
require several settings:- The Things API token - this is required for identifying the client
- A message provider - to support WebSocket based communication to the “Bosch IoT Things” backend
- An endpoint - this is necessary to set the endpoint based on the
environment you have subscribed for.
The default is set towss://things.s-apps.de1.bosch-iot-cloud.com/ws/1
- for the direct WebSocket based communication to Bosch IoT Things on Bosch IoT Cloud (BIC).
Find the technical endpoints for the specific
environment in our FAQ section How to find the endpoints for my subscription?.
Example:
ThingsClientFactory.configurationBuilder()
.apiToken(THINGS_API_TOKEN)
.providerConfiguration(MessagingProviders
.thingsWebsocketProviderBuilder()
.authenticationConfiguration(authenticationConfiguration)
.endpoint("wss://things.eu-1.bosch-iot-suite.com")
.build())
...
Enhancements
Additionally to the direct WebSocket communication to your digital twins at Bosch IoT Things (similar to CRIC 2.4.x), the new client provides a second communication channel: the live channel. The live channel proves useful for client to client communication via the Bosch IoT Things WebSocket backed by the Things protocol.
Migration notes
Coming from CRIC 2.4.x you will need to perform following changes:
- Adjust the initialization of the Things Client
(you will get compile errors otherwise)- Use “ThingsClientFactory” to create client instances and configuration builders
- Set the “providerConfiguration()” to choose which communication to the Things service to use
- Set the API token of your solution instance when initializing the Things Client
- Remove all your calls to “IntegrationClient#subscriptions()”, “SubscriptionIntegration#create()”, “SubscriptionIntegration#delete()”, “SubscriptionIntegration#consume()”, and “SubscriptionIntegration#suspend()”.\ Instead, for starting the consumption of changes and messages, invoke the “CommonThingIntegration#startConsumption()” method once.
-Replace all calls to “client.things()” with a more specific one:
- “client.twin()” - for updating/retrieving values from the Things service, or
- “client.live()” - for sending/consuming messages to/from other clients
API
things-client-api 3.0.0 - deprecated
Compared to its previous version cr-integration-api 3.3.0 (deprecated) the new API comes with following changes:
- New Maven coordinates:
<groupId>com.bosch.iot.things.client
</groupId>
<artifactId>things-client-api
</artifactId> - Specifying a namespace within the Thing ID is mandatory.
In case you have already created Things with empty namespaces, you will need to add a namespace from now on.
Breaking Changes
Removed
SubscriptionIntegration
classIntegrationClient#subscriptions()
methodFeatureHandle#message()
methodThingHandle#message()
methodThingIntegration#message()
methodSubscriptionNotFoundException
(non used)SubscriptionConsumeOptions
- the options do not apply any longer.SubscriptionIntegration
methods, as there is no longer the need to create or delete subscriptionsSubscriptionIntegration#create()
SubscriptionIntegration#delete()
Migration notes
Coming from cr-integration-api
- Remove all calls to
SubscriptionIntegration#consume()
andSubscriptionIntegration#suspend()
Use the methodsCommonThingIntegration#startConsumption()
andCommonThingIntegration#suspendConsumption()
instead. IntegrationClient#things()
was deprecated- Use
IntegrationClient#twin()
instead, in order to change things managed by the Things service (also called “Twins” now) and register for changes issued by the Things service. - Use
IntegrationClient#live()
instead, in order to send/receive messages via the client.
Live messages will just be routed by the Things service without applying any changes at thing (twin) entity.
- Use
Find a schematic view of twin and live messages at
Bosch IoT Things Protocol.
See as well section things-client 3.0.0 at the top of the page.