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.

tip 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 the TwinConfiguration and the LiveConfiguration.
  • The IntegrationClient was renamed to ThingsClient
  • The IntegrationClientConfiguration class was removed.
    Please use instead the TwinConfiguration, the LiveConfiguration, 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 TwinConfiguration and the LiveConfiguration 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 to wss://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).

tip 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 class
  • IntegrationClient#subscriptions() method
  • FeatureHandle#message() method
  • ThingHandle#message() method
  • ThingIntegration#message() method
  • SubscriptionNotFoundException (non used)
  • SubscriptionConsumeOptions - the options do not apply any longer.
  • SubscriptionIntegration methods, as there is no longer the need to create or delete subscriptions
    • SubscriptionIntegration#create()
    • SubscriptionIntegration#delete()

Migration notes

Coming from cr-integration-api

  • Remove all calls to SubscriptionIntegration#consume() and SubscriptionIntegration#suspend()
    Use the methods CommonThingIntegration#startConsumption() and CommonThingIntegration#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.

tip 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.

Imprint Legal info Privacy statement