Pelion Cloud SDK for Java

Due to a redirected focus onto future development of the Pelion Device Management APIs, this SDK Is no longer actively supported and there is no commitment for future maintenance releases.

The open source project and corresponding packages for this SDK remain publicly available.

Existing applications developed using the SDK will continue to operate against existing Pelion Device Management REST APIs (assuming that those APIs are not subject to the deprecation process for commercial customers). New APIs supported by Pelion Device Management will only be available through the REST APIs.

It is recommended that for ongoing development, applications which previously used the SDK should be migrated over time to access the Pelion Device Management REST APIs directly.

Please see this page, which provides additional information on using the REST APIs. By following this guide, you will learn how to build a web application using the REST APIs directly.

The Pelion Device Management SDK (formerly known as Mbed Cloud SDK) provides a simplified interface to the Pelion Device Management APIs by exposing functionality using conventions and paradigms familiar to Java developers.

Prerequisites

• Java > 1.7 tested with Oracle JRE

Logging

• The SDK uses SLF4j and hence, any supported logging framework (e.g. java.util.logging, logback, log4j) can be used by your application.

Distribution

In order to best meet your requirements, Java SDK is packaged in three different ways:

• Individual Jars
• Distribution ZIP. See related gradle plugin for more details.
• A fat jar comprising the SDK and all its dependencies.

Getting started

Artefacts listed above are published on JCenter and Maven Central. They can therefore be retrieved and included into your project using the package manager of your choice. To do so, please follow the instructions present on one of these artefact repositories (Bintray page of the project).

For example, if using Gradle, add the following compile dependency to build.gradle:

implementation 'com.arm.mbed.cloud.sdk:mbed-cloud-sdk:x.y.z'

Current artefacts are not fully tailored for Android but can be used as is on this mobile platform. However, the oltu dependency will have to be excluded to remove any compilation issue (e.g. Error converting bytecode to dex:\nCause: com.android.dex.DexException: Multiple dex files define Lorg/apache/oltu/oauth2/common/domain/credentials/Credentials. To do so, import the SDK in the gradle file, as follows:

implementation( 'com.arm.mbed.cloud.sdk:mbed-cloud-sdk:x.y.z' ){
    // Excluding a particular transitive dependency:
    exclude group: 'org.apache.oltu.oauth2'
}

Usage

These instructions can also be found in the official documentation:

1. Create an API key on Pelion Device Management Portal.
2. Import the SDK to your project using one of the packages listed above.
3. Create a configuration object:

       String apiKey = "<apikey>"; //API key to use for contacting Pelion Cloud.
       ConnectionOptions config =  ConnectionOptions.newConfiguration(apiKey);
       config.setClientLogLevel(CallLogLevel.BODY);//Defines the logging level of HTTP communications. See CallLogLevel for more information.

4. You are ready to go.

       try (Sdk sdk = Sdk.createSdk(config); DeviceListDao dao = sdk.foundation().getDeviceListDao()) {
           dao.list().forEach(System.out::println);
       } catch (MbedCloudException | IOException e) {
           e.printStackTrace();
       }

Versioning

The SDK version scheme follows Semantic versioning

<SDK major>.<SDK minor>.<SDK bugFix>

Documentation and examples

The SDK guide and examples are available on GitHub

The documentation contains many examples covering various Use Cases that you may have. In each case you can compare the Java implementation with alternatives in languages supported by the other Pelion Device Management SDKs.

See API reference (i.e. javadoc) at https://cloud.mbed.com/docs/latest/mbed-cloud-sdk-java/. or locally hosted at GitHub

For specific Java usage examples, please have a look at the example project.

Contributing

The Pelion Device Management SDK for Java is open source and we would like your help. There is a brief guide on how to get started in CONTRIBUTING.md.

Project

• All code inside *.internal.* packages or annotated as @Internal is considered private API and should not be relied upon at all.
• Classes annotated as @Module contain all Arm Pelion Device Management REST APIs
• Methods annotated as @API are low-level functions which can be used to interact with Pelion Cloud. However, it is advised to use DAOs instead.
• APIs, objects or methods annotated as @Deprecated are supported until the next major release and will be removed later on. It is highly recommended to stop using them.
• Methods with @Daemon annotation should be used to monitor SDK daemon threads.

Licence

Pelion Device Management SDK for Java is free-to-use and licensed under the Apache License 2.0. See LICENCE file for more information.