cloud-of-things / cot-java-rest-sdk

Cloud of Things Java Rest SDK (Cloud der Dinge Java Rest SDK)

Cloud of Things Java Rest SDK

The Cloud of Things (German Cloud der Dinge) is a platform for the Internet of Things by T-Systems International GmbH. Inside this repository you will find a Java based SDK to interface with the Cloud of Things API.

Current version is: 2.0.0

Usage

Add this to your pom.xml to include the SDK in your Maven Repo

<dependency>
    <groupId>com.telekom.m2m.cot</groupId>
    <artifactId>java-rest-client</artifactId>
    <version>2.0.0</version>
</dependency>

Example of a basic connect to the platform:

CloudOfThingsPlatform cotPlatform = new CloudOfThingsPlatform("hostname", new CotCredentials("tenant", "username", "password"));
InventoryApi inventoryApi = cotPlatform.getInventoryApi();
inventoryApi.get("idOfManagedObject");

Developers can find further information and examples in the DEVELOPER.md file.

Java Doc

You can find the Java Doc of the latest release here: http://cloud-of-things.github.io/cot-java-rest-sdk/

Release Notes

Short information about what has changed between releases.

Release 2.0.0

• Measurement real time notification functionality was moved from InventoryApi to MeasurementApi

• Prevent injection in update method (Pull Request #90).

• More robust deserialization catching IllegalArgumentException being thrown by Spring Boot Class Loader for properties like "A+:1" in ThreePhaseElectricityMeasurement (Pull Request #91).

• Fix erroneously wrapped numeric values in deserialized ExtensibleObjects (Pull Request #92), e.g.: serialized Object: temperature=ExtensibleObject{anyObject={unit=°C, value=100.0}} will be deserialized into:

  OLD:
  "temperature":{
      "value":{
          "value":"100.0"
      },
      "unit":"°C"
  }
  
  FIXED:
  "temperature":{
      "value":100.0,
      "unit":"°C"
  }
  

• Includes Pull Request #94:

  • Usage of newest dependencies
  • Cleanup and improvements according to code inspection

• EventApi provides the update of events as well now. (Pull Request #95)

• Fixed cast in getSource() method of Alarm and Event

• Added the getter as counterpart of set(Object) in ExtendedObject

• Includes (Pull Request #96):

  • Fixed some unstable integration tests due to maybe changed behavior of the c8y API
  • Provided more details from the c8y error message in CotSdkException

Release 1.1.0

• Includes Pull Request #73: Efficiently iterate over all objects in a collection via Java 8 Stream (accessible via stream()): pagination is automatically performed in the background
• Resolve issue #72: Improved paging performance
• Fix double slashes in url (Pull Request #77)

Release 1.0.5

• Provide functionality to get all SmartREST Templates by X-ID
• Resolve issue #52: provide http status code in thrown exception in getMeasurement()

Release 1.0.4

• Improve usage of accept and content-type headers in rest client
• Improve usage of OkHttpClient so that lesser resources will be used
• Fix handling of binary data using byte array
• Remove double slashes in rest api paths to avoid http code 404
• Resolve issue #51: provide failure reason for failed operations
• Resolve issue #53: provide a new method for creation NewDeviceRequests
• Handle filters as enum and validate filters supported by cot
• Improve Notification class which now provides realtime action

Release 1.0.2

• Update of okhttp.
• Better integration-tests.
• Better login-process (include tenant in username).
• NewDeviceRequestStatus-enum.
• Refactoring.

Release 1.0.0

• Improved Examples: Add examples for SDK-Users (see DEVELOPER.md)
• Implemented Sensor Library
• Implemented Binaries API
• Final adjustments for MIT License
• Improve ManagedObject-deserialization
• Credentials for integration tests will be read from environment variables instead of property file
• Refactor device permission handling
• A lot of improvements and cleanups

Release 0.6.1

• Provides and uses SmartRequest/-Response classes

Release 0.6.0

• Complete Device control
• Complete Real-time notifications
• Complete Real-time statements
• Complete Device management library
• Complete Users API
• Complete Retention Rule API
• Complete SmartREST API
• Complete Audit API
• Refactor collection classes extending JsonArrayPagination base class

Release 0.5.0

• Most important change is the removal of right now unused parameter tenant in CloudOfThingsPlatform constructor (See commit 62079fe).
• Unsuccessful creation/store of objects in the CoT will now result in a CotSdkException.
• New method DeviceCredentialsApi.NewDeviceRequest(..).
• MeasurementsApi supports creating measurement collections.

Release 0.4.0

• Improvements, e.g. connection exception handling
• Short information about what has changed between releases.
• Bulk Operations (beta)

Release 0.3.0

• Complete Inventory
• Get ManagedObjects in Collection
• Complete Alarm API
• Retrieve collections
• Update Alarms
• Complete Device Credentials API
• Complete IdentityApi

Release 0.2.0

• Complete Events
• Complete Device registration process
• Implement removal of devices and its belongings
• Complete MeasurementsAPI
• Refactor from single methods to Query objects.
• Filter Date
• Filter FragmentType
• ... and combinations
• DELETE - delete a measurement collection
• Complete Inventory
• DELETE a managed object reference

cot-java-rest-sdk's Issues

Release 1.1.1

Could you please release a new version 1.1.1 with recent fixes from the current develop branch so that it is available in nexus?

Deprecated Filter methods could stay supported

The deprecation is only because of the magic strings inside that are not secured by enums. But the methods could internally use the FilterBy too, then they would be safer. They are sometimes more convenient compared to the enum.

Deprecate DeviceCredentialsApi.getCredentials(..)

There is an IOException in DeviceCredentialsApi public DeviceCredentials getCredentials(String deviceId) throws IOException. Should be set to deprecated and replaced by unchecked exception.

Adding failureReason to Operation update

Updating an Operation just PUT's the new status to CoT.
It would be great to be able to set a "failureReason" wich is displayed in operation audit.

Wrong Http-status = 0 in Java-class --> CotSdkException.java for exception-handling in case of "Measurement not found" --> Java-Sdk version 1.0.0

For all HTTP-responses unequal to "Measurement Id not found" the HTTP-status code is set corrcetly unequal to '0'.

In case of "Measurement Id not found" the HTTP-response status code is set always to '0' (reason: wrong constructor selected)

Test for measurement not found:
valid DeviceId = 4471037 in CoT-Tenant

CloudOfThingsPlatform cotPlatform = new CloudOfThingsPlatform("url", new CotCredentials("tenant", "user", "password"));

try {
Measurement cotDevice4471037 = cotPlatform.getMeasurementApi().getMeasurement("4471037");
System.out.println("cotDevice4471037 = " + cotDevice4471037);
return "cotDevice4471037 = " + cotDevice4471037;
}
catch(CotSdkException e){
System.out.println(e.getMessage());
return "error: status=" + e.getHttpStatus() + " message=" + e.getMessage();
}

TestResult:
error: status=0 message=Measurement not found (id='4471037')

Small Bug in getMeasurements

If I use MeasurementApi.getMeasurements(x) I always get just 5 Measurements, regardless what x is.

OperationStatus cannt map the status WAITING_FOR_CONNECTION

Hi,
when try to register a device in the cloud as parent device, there is a method in DeviceControlApi.createNewDevice that receive an operation as parameter. This method also, doesnt get the result fron the CoT, is a bug too. Then, when i do the request manually, i try to check the status of the operation and get this error that describe below:

java.lang.IllegalArgumentException: No enum constant com.telekom.m2m.cot.restsdk.devicecontrol.OperationStatus.WAITING_FOR_CONNECTION

In the class OperationStatus doesnt exists a map for that value, can you please fix this? also will be nice to have the other bug mentioned before, because the method DeviceControlApi.createNewDevice doesnt get the response from the CoT, is returning the same parameter given.

Thanks.

CloudOfThingsRestClient does not close the connection if the request was not successful

Hi,

CloudOfThingsPlatform creates a OkHttpClient object that it used for the class CloudOfThingsRestClient.java. When the request failed (user/password not correct, etc.) the connection is not closed by CloudOfThingsRestClient and continues acumulating open sockets until its not possible do more requests.

com.telekom.m2m.cot.restsdk.util.CotSdkException: Error in request
Caused by: java.net.SocketException: Zu viele offene Dateien
at java.net.Socket.createImpl(Socket.java:460)
at java.net.Socket.getImpl(Socket.java:520)
at java.net.Socket.setSoTimeout(Socket.java:1141)
at okhttp3.internal.connection.RealConnection.connectSocket(RealConnection.java:221)
at okhttp3.internal.connection.RealConnection.connect(RealConnection.java:149)
at okhttp3.internal.connection.StreamAllocation.findConnection(StreamAllocation.java:195)
at okhttp3.internal.connection.StreamAllocation.findHealthyConnection(StreamAllocation.java:121)
at okhttp3.internal.connection.StreamAllocation.newStream(StreamAllocation.java:100)
at okhttp3.internal.connection.ConnectInterceptor.intercept(ConnectInterceptor.java:42)
at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.java:92)
at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.java:67)
at okhttp3.internal.cache.CacheInterceptor.intercept(CacheInterceptor.java:93)
at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.java:92)
at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.java:67)
at okhttp3.internal.http.BridgeInterceptor.intercept(BridgeInterceptor.java:93)
at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.java:92)
at okhttp3.internal.http.RetryAndFollowUpInterceptor.intercept(RetryAndFollowUpInterceptor.java:120)
at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.java:92)
at okhttp3.internal.http.RealInterceptorChain.proceed(RealInterceptorChain.java:67)
at okhttp3.RealCall.getResponseWithInterceptorChain(RealCall.java:185)
at okhttp3.RealCall.execute(RealCall.java:69)
at com.telekom.m2m.cot.restsdk.CloudOfThingsRestClient.getResponse(CloudOfThingsRestClient.java:431)

JsonArray pagination is not efficient

Currently it seems that the existence of a "next" page is determined by the availability of the next ressource. Before doing that request we might check for totalPages (optional, but could be there) and if the number of elements on the current page is < the pageSize, in which case no next page will exist.

http://cumulocity.com/guides/reference/rest-implementation/

Add TenantId to CloudOfThingsPlatform initialization

The class CotCredentials has tenant, username und password property but the CloudOfThingsPlatform initialization just uses username and password. Everything works fine until you want to dynamically change CoT Tenant, because at the moment you have to provide exact tenant address in host property.

Problem can be fixed with adding the tenant id to username.

Example: testuser --> awesometenant/testuser

Then you can use management tenant as host and changing tenants just with changing tenant id.

IdentityApi -> Just usable with ExternalId

The class IdentityApi just uses methods with ExternalId as arguments. Should also be able to use with ID String too.