client-sdk-java.md

title	keywords	tags	permalink
Client SDK Java		client_sdk	client-sdk-java.html

A client SDK for Java in order to interact with digital twins provided by an Eclipse Ditto backend.

Features

• Digital twin management: CRUD (create, read, update, delete) of Ditto things
• Change notifications: consume notifications whenever a "watched" digital twin is modified
• Send/receive messages to/from devices connected via a digital twin
• Use the live channel in order to react on commands directed to devices targeting their "live" state

Communication channel

The Ditto Java client interacts with an Eclipse Ditto backend via Ditto's WebSocket sending and receiving messages in Ditto Protocol.

Usage

Maven coordinates:

<dependency>
   <groupId>org.eclipse.ditto</groupId>
   <artifactId>ditto-client</artifactId>
   <version>${ditto-client.version}</version>
</dependency>

Instantiate & configure a new Ditto client

To configure your Ditto client instance, use the org.eclipse.ditto.client.configuration package in order to

• create instances of AuthenticationProvider and MessagingProvider
• create a DittoClient instance

For example:

AuthenticationProvider authenticationProvider =
    AuthenticationProviders.clientCredentials(ClientCredentialsAuthenticationConfiguration.newBuilder()
        .clientId("my-oauth-client-id")
        .clientSecret("my-oauth-client-secret")
        .scopes("offline_access email")
        .tokenEndpoint("https://my-oauth-provider/oauth/token")
        .build());

MessagingProvider messagingProvider = MessagingProviders.webSocket(WebSocketMessagingConfiguration.newBuilder()
    .endpoint("wss://ditto.eclipse.org")
    .jsonSchemaVersion(JsonSchemaVersion.V_1)
    // optionally configure a proxy server or a truststore containing the trusted CAs for SSL connection establishment
    .proxyConfiguration(ProxyConfiguration.newBuilder()
        .proxyHost("localhost")
        .proxyPort(3128)
        .build())
    .trustStoreConfiguration(TrustStoreConfiguration.newBuilder()
        .location(TRUSTSTORE_LOCATION)
        .password(TRUSTSTORE_PASSWORD)
        .build())
    .build(), authenticationProvider);

DittoClient client = DittoClients.newInstance(messagingProvider);

Use the Ditto client

Manage twins

client.twin().create("org.eclipse.ditto:new-thing").handle((createdThing, throwable) -> {
    if (createdThing != null) {
        System.out.println("Created new thing: " + createdThing);
    } else {
        System.out.println("Thing could not be created due to: " + throwable.getMessage());
    }
    return client.twin().forId(thingId).putAttribute("first-updated-at", OffsetDateTime.now().toString());
}).get(); // this will block the thread! work asynchronously whenever possible!

Subscribe for change notifications

client.twin().startConsumption().get();
System.out.println("Subscribed for Twin events");
client.twin().registerForThingChanges("my-changes", change -> {
   if (change.getAction() == ChangeAction.CREATED) {
       System.out.println("An existing Thing was modified: " + change.getThing());
       // perform custom actions ..
   }
});

Send/receive messages

Register for receiving messages with the subject hello.world on any thing:

client.live().registerForMessage("globalMessageHandler", "hello.world", message -> {
   System.out.println("Received Message with subject " +  message.getSubject());
   message.reply()
      .statusCode(HttpStatusCode.IM_A_TEAPOT)
      .payload("Hello, I'm just a Teapot!")
      .send();
});

Send a message with the subject hello.world to the thing with ID org.eclipse.ditto:new-thing:

client.live().forId("org.eclipse.ditto:new-thing")
   .message()
   .from()
   .subject("hello.world")
   .payload("I am a Teapot")
   .send(String.class, (response, throwable) ->
      System.out.println("Got response: " + response.getPayload().orElse(null))
   );

Further Examples

For further examples on how to use the Ditto client, please have a look at the class DittoClientUsageExamples which is configured to connect to the Ditto sandbox.