Microservice SDK for Java

Introduction

This section describes how to develop and deploy microservices on top of Cumulocity using the Microservice SDK for Java. It also contains a Hello world tutorial that you may follow to get the basics of developing microservices using Java. After you have successfully deployed your first microservice to Cumulocity, you may also continue with the section Developing microservices to learn more about other features and capabilities of the SDK.

These are some useful references to get started with the basic technologies underlying the SDK:

• The client libraries use the Cumulocity REST interfaces as underlying communication protocol as described in the section Using the REST interface.
• All examples are open source and can be reviewed at the Cumulocity microservices examples repository.

If you face any issue or need support, refer to Cumulocity Tech Community. You will find plenty of useful information there.

Hello world tutorial for Java

Here you will learn how to create your first microservice that can be deployed on the Cumulocity platform using the Microservice SDK for Java.

Requests to a microservice can be authenticated using basic authentication or OAuth. Refer to Authentication and authorization for more details.

Prerequisites

You must have Cumulocity credentials and a dedicated tenant. In case you do not have that yet, create an account on the Cumulocity platform, for example by using a free trial. At this step you will be provided with a dedicated URL address for your tenant.

Verify that you have a recommended Java version installed together with Maven 3 or higher. It can be downloaded from the Maven website.

$ mvn -v
Apache Maven 3.8.5
Maven home: /Library/Maven/apache-maven-3.8.5
Java version: 17.0.6, vendor: Oracle Corporation
Java home (runtime): /Library/Java/JavaVirtualMachines/jdk-17.0.6.jdk/Contents/Home
OS name: "mac os x", version: "10.14.6", arch: "x86_64", family: "mac"

You will also need a Docker installation, and in case that you don’t have it yet, go to the Docker website to download and install it.

Cumulocity microservices are Docker containers for the Linux/Amd64 platform. Other architectures are currently not supported. The Docker engine must provide the API version 1.38 or newer. This is the case for Docker versions 18.06 and later. Use the following command to verify your Docker installation:

$ docker version
Client: Docker Engine - Community
 Version:           20.10.14
 API version:       1.41
 Go version:        go1.16.15
 Git commit:        a224086
 Built:             Thu Mar 24 01:47:57 2022
 OS/Arch:           linux/amd64
 Context:           default
 Experimental:      true

Server: Docker Engine - Community
 Engine:
  Version:          20.10.14
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.16.15
  Git commit:       87a90dc
  Built:            Thu Mar 24 01:45:46 2022
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.5.11
  GitCommit:        3df54a852345ae127d1fa3092b95168e4a88e2f8
 runc:
  Version:          1.0.3
  GitCommit:        v1.0.3-0-gf46b6ba
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

Developing the “Hello world” microservice

You can download the source code of this example from our GitHub repository to build and run it using your favorite IDE, or follow the instructions below to guide you step-by-step for you to have a better understanding of the code and what must be done/configured.

Create a Maven project

Use the Maven Archetype Plugin to create a Java project from an existing Maven template. Use c8y.example as your groupId, hello-microservice-java as your artifactId, and set the version following the SemVer format as specified in Microservice manifest.

$ mvn archetype:generate -DgroupId=c8y.example -DartifactId=hello-microservice-java -Dversion=1.0.0-SNAPSHOT -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

This will create a folder hello-microservice-java in the current directory with a skeleton structure for your project.

Specify the properties

You will find the pom.xml file inside the hello-microservice-java folder. Edit this file and add a <properties> element to set the -source and -target of the Java Compiler using version 17. This example uses Spring Boot to quickly build and create the application using the Spring Framework. Hence, also specify in the <properties> element the version to use as follows:

<properties>
    <java.version>17</java.version>
    <maven.compiler.source>${java.version}</maven.compiler.source>
    <maven.compiler.target>${java.version}</maven.compiler.target>
    <spring-boot-dependencies.version>2.5.14</spring-boot-dependencies.version>
</properties>

Add the microservice library

You must specify the version of the Cumulocity’s microservice library to be used. This can be found on the platform; at the top-right corner, click the tenant user and find the backend version on the pop-up menu.

Alternatively, you can retrieve the backend version with a GET request to /tenant/system/options/system/version.

The response looks like this:

{
    "category": "system",
    "value": "1016.0.117",
    "key": "version"
}

See also Tenants in the Cumulocity OpenAPI Specification.

In the <properties> element specified above, add a child element <c8y.version> with the backend version of your tenant. Also add a <microservice.name> child element to name your microservice application.

    <c8y.version>1016.0.117</c8y.version>
    <microservice.name>hello-microservice-java</microservice.name>

Add repositories and dependencies

Your pom.xml file must have <repository> and <pluginRepository> elements to point to the Cumulocity Maven repository which stores the client libraries.

<repositories>
    <repository>
        <id>cumulocity</id>
        <layout>default</layout>
        <url>https://download.cumulocity.com/maven/repository</url>
    </repository>
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>public</id>
        <url>https://download.cumulocity.com/maven/repository</url>
    </pluginRepository>
</pluginRepositories>

Also add a dependency for the Microservice SDK library inside the <dependencies> node.

<dependencies>
    ...
    <dependency>
        <groupId>com.nsn.cumulocity.clients-java</groupId>
        <artifactId>microservice-autoconfigure</artifactId>
        <version>${c8y.version}</version>
    </dependency>
</dependencies>

Add a <dependencyManagement> element to automatically manage the required artifacts needed for your microservice application.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.nsn.cumulocity.clients-java</groupId>
            <artifactId>microservice-dependencies</artifactId>
            <version>${c8y.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Configure the build plugins

Your microservice application must be packed as a Docker image in a ZIP file including all the required dependencies. To achieve that, include in your pom.xml file build plugins as follows:

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <version>${spring-boot-dependencies.version}</version>
            <configuration>
                <mainClass>c8y.example.App</mainClass>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>repackage</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        <plugin>
            <groupId>com.nsn.cumulocity.clients-java</groupId>
            <artifactId>microservice-package-maven-plugin</artifactId>
            <version>${c8y.version}</version>
            <executions>
                <execution>
                    <id>package</id>
                    <phase>package</phase>
                    <goals>
                        <goal>package</goal>
                    </goals>
                    <configuration>
                        <name>${microservice.name}</name>
                        <image>${microservice.name}</image>
                        <encoding>UTF-8</encoding>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

The name of the generated ZIP file is specified in the image element as <image>${microservice.name}</image>. It takes the name from the previously defined property microservice.name, which in this case is hello-microservice-java.

Create a Java application

Edit the App.java file located in the folder /src/main/java/c8y/example with the following content:

package c8y.example;

import com.cumulocity.microservice.autoconfigure.MicroserviceApplication;
import org.springframework.boot.SpringApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@MicroserviceApplication
@RestController
public class App {
    public static void main (String[] args) {
        SpringApplication.run(App.class, args);
    }

    @RequestMapping("hello")
    public String greeting (@RequestParam(value = "name", defaultValue = "World") String you) {
        return "Hello " + you + "!";
    }
}

The code uses four annotations; three are part of the Spring Framework and one of the Cumulocity Microservice SDK. The @RestController annotation marks the class as a controller where every method returns a domain object instead of a view. The @RequestMapping annotation ensures that HTTP requests to the /service/<microservice-name>/hello endpoint are mapped to the greeting() method. @RequestParam binds the value of the query string parameter name into the you parameter of the greeting() method. Refer to the Spring Guides for more details about building RESTful Web Services using the Spring Framework.

Employing the @MicroserviceApplication annotation is a simple way to add the required behavior for Cumulocity microservices including:

• Security
• Subscription
• Health check endpoint at /service/<microservice-name>/health
• Context
• Settings
• Internal platform API
• Spring Boot application

Configure the microservice application

Create the directory src/main/resources to contain an application.properties file specifiying the name of the microservice application and the server port:

application.name=my-first-microservice
server.port=80

Create the directory src/main/configuration to contain a cumulocity.json file. This is the manifest file and it is required to deploy the microservice in the Cumulocity platform.

{
  "apiVersion": "2",
  "version": "@project.version@",
  "provider": {
    "name": "Cumulocity"
  },
  "isolation": "MULTI_TENANT",
  "replicas": 2,
  "livenessProbe": {
    "httpGet": {
      "path": "/health"
    },
    "initialDelaySeconds": 60
  },
  "readinessProbe": {
    "httpGet": {
      "path": "/health"
    },
    "initialDelaySeconds": 60
  },
  "requiredRoles": [ ]
}

Build the microservice application

In a terminal, navigate to the folder where your pom.xml is located and execute the following Maven command:

$ mvn clean install

After a successful build, you will find a ZIP file inside the target directory.

$ ls target | grep zip
hello-microservice-java-1.0.0-SNAPSHOT.zip

Deploying the “Hello world” microservice

To deploy your microservice on the Cumulocity platform you need:

• A valid tenant, a user and a password in order to access Cumulocity.
• The ZIP file built with Maven on the previous steps.

In the Administration application, navigate to Ecosystem > Microservices, and click Add microservice.

Upload the ZIP file for your microservice application and click Subscribe to subscribe the microservice to your tenant.

Once the ZIP file has been uploaded successfully, you will see a new microservice application created.

Test the deployed microservice

Employing your tenant credentials, you can test the microservice on any web browser using the URL as follows:

https://<yourTenantDomain>/service/hello-microservice-java/health

You can also use third-party applications or commands to make a GET request to your microservice endpoint. To do so, you need:

• A valid tenant, a user and a password in order to access Cumulocity.
• A basic authorization header "Authorization: Basic <Base64(<tenantID>/<username>:<password>)>".

For instance, if your tenant ID, username and password are t0071234, testuser and secret123 respectively, you can get the Base64 string with the following command:

$ echo -n t0071234/testuser:secret123 | base64
dDAwNzEyMzQvdGVzdHVzZXI6c2VjcmV0MTIz

and your authorization header would look like Authorization: Basic dDAwNzEyMzQvdGVzdHVzZXI6c2VjcmV0MTIz. Employing the cURL command you can test your microservice as follows:

$ curl -H "Authorization: <AUTHORIZATION>" https://<yourTenantDomain>/service/hello-microservice-java/hello?name=Skywalker

Most tools should already support the Cumulocity Authorization header out of the box. Simply use <tenantId>/<username> as username and <password> as password. In modern versions, for example, the above cURL command can also look like below, and the header will be generated automatically:

$ curl --user "<TENANTID>/<USERNAME>:<PASSWORD>" https://<yourTenantDomain>/service/hello-microservice-java/hello?name=Skywalker

Running the microservice locally

You can run the Docker container locally in order to test the REST calls from the microservice to Cumulocity.

To run a microservice which uses the Cumulocity API locally, you need:

• A valid tenant, a user and a password in order to access Cumulocity.
• An authorization header as “Basic <Base64(<tenantID>/<username>:<password>)>”.

Create the application

If the application does not exist, create a new application on the Cumulocity platform employing a POST request.

POST <URL>/application/applications

HEADERS:
  "Authorization": "<AUTHORIZATION>"
  "Content-Type": "application/vnd.com.nsn.cumulocity.application+json"
  "Accept": "application/vnd.com.nsn.cumulocity.application+json"

BODY:
{
  "name": "<APPLICATION_NAME>",
  "type": "MICROSERVICE",
  "key": "<APPLICATION_NAME>-key"
}

You must replace the values <URL> with the URL of your Cumulocity tenant (domain), <AUTHORIZATION> is Basic with a Base64 encoded string, and for <APPLICATION_NAME> use the desired name for your microservice application and its key name.

The cURL command can be used to create the application with a POST request:

$ curl -X POST -s \
  -d '{"name":"local-microservice-java","type":"MICROSERVICE","key":"my-hello-world-ms-key"}' \
  -H "Authorization: <AUTHORIZATION>" \
  -H "Content-Type: application/vnd.com.nsn.cumulocity.application+json" \
  -H "Accept: application/vnd.com.nsn.cumulocity.application+json" \
  "<URL>/application/applications"

In case of errors, such as invalid names, you will get the details printed in the console. When the application is created successfully, you will get a response in JSON format similar to the following example:

{
    "availability": "PRIVATE",
    "contextPath": "local-microservice-java",
    "id": "<APPLICATION_ID>",
    "key": "my-hello-world-ms-key",
    "manifest": {
        "noAppSwitcher": true,
        "settingsCategory": null
    },
    "name": "local-microservice-java",
    "owner": {
        "self": "...",
        "tenant": {
            "id": "<TENANT_ID>"
        }
    },
    "requiredRoles": [],
    "roles": [],
    "self": "<URL>/application/applications/<APPLICATION_ID>",
    "type": "MICROSERVICE"
}

In the Administration application, navigate to Ecosystem > Microservices. There you will see the created microservice.

Acquire the microservice bootstrap user

You will need the bootstrap user credentials in order to run the microservice locally. Get the details of your bootstrap user with a GET request.

GET <URL>/application/applications/<APPLICATION_ID>/bootstrapUser

HEADERS:
  "Authorization": <AUTHORIZATION>
  "Content-Type": application/vnd.com.nsn.cumulocity.user+json

The response looks like this:

{
    "password": "<BOOTSTRAP_USER_PASSWORD>",
    "name": "<BOOTSTRAP_USER_NAME>",
    "tenant": "<BOOTSTRAP_USER_TENANT>"
}

Run the Docker container

The Docker image was built using your local Docker repository during the Maven build. Note, that by default the image is deleted to keep your registry clean during development. You can change this by adding the property microservice.package.deleteImage=false to the maven command or pom.xml.

$ mvn clean install -Dmicroservice.package.deleteImage=false

You can list all the Docker images available with the following command:

$ docker images

It yields an output similar to this:

REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
hello-microservice-java   1.0.0-SNAPSHOT      3e5e7aeea7bc        52 minutes ago      143MB

Get your IMAGE ID and TAG from the list. While not strictly a means of identifying a container, you can specify a version of an image (TAG) you would like to run the container with. Run the Docker container for the microservice:

$ docker run -p 8082:80 -e C8Y_BOOTSTRAP_TENANT=<BOOTSTRAP_USER_TENANT> \
  -e C8Y_BOOTSTRAP_USER=<BOOTSTRAP_USER_NAME> \
  -e C8Y_BOOTSTRAP_PASSWORD=<BOOTSTRAP_USER_PASSWORD> \
  -e C8Y_MICROSERVICE_ISOLATION=MULTI_TENANT \
  -i -t -e C8Y_BASEURL=<URL> <IMAGE_ID>

-p 8082:80 will expose your port 80 to a port on your host system, for example, 8082.

If your Docker image has run successfully, you shall see the output on the console similar to the one below.

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::        (v2.5.14)

2022-10-21 15:53:07.510  INFO 7 --- [main] c8y.example.App                          : Starting App on dff01acae6d8 with PID 7 (/data/hello-microservice-java.jar started by root in /)
...
2022-10-21 15:53:17.583  INFO 7 --- [main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 80 (http)
2022-10-21 15:53:17.598  INFO 7 --- [main] c8y.example.App                          : Started App in 11.32 seconds (JVM running for 12.192)

Subscribe to the microservice

In the Administration application, navigate to Ecosystem > Microservices. Locate your microservice application and click it to open its details. On the top right, click Subscribe.

At this point, you may open your favorite browser and test your microservice at http://localhost:8082/hello. Enter your bootstrap user credentials using <tenant>/<username> and your password.

You may also use the name parameter, for example, http://localhost:8082/hello?name=Neo.

Improving the microservice

Now that you have done your first steps, check out the section Developing microservices to find out what else can be implemented. Review also the Java example in this guide to learn using more features of the microservice SDK and REST API by employing third-party services.

IP-tracker microservice

Developing the IP-tracker microservice

This microservice application creates a warning alarm message (for demonstration purposes) and it exposes endpoints to:

• Verify that the microservice is up and running.
• Pass a parameter to the platform and return a formatted string.
• Get some of the environment variables and the microservice service settings.
• Track a user’s approximate location and store it in the platform.
• Get the tracked IPs and locations.

It also uses the Cumulocity UI to display the tracked locations on a map.

Update the Project Object Model

Assuming that you have the base code presented in our Hello world tutorial for Java, edit your pom.xml file changing the artifactId and microservice.name of your microservice to iptracker-microservice. Also add a child element <java.version> to the <properties> element to specify the Java version you want to use. Your pom.xml file should contain a snippet similar to:

<name>iptracker-microservice</name>
<artifactId>iptracker-microservice</artifactId>
<properties>
    <java.version>17</java.version>
    <maven.compiler.source>${java.version}</maven.compiler.source>
    <maven.compiler.target>${java.version}</maven.compiler.target>
    <spring-boot-dependencies.version>2.5.14</spring-boot-dependencies.version>
    <c8y.version>1016.0.117</c8y.version>
    <microservice.name>iptracker-microservice</microservice.name>
</properties>

Finally, add the following dependency:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <scope>compile</scope>
</dependency>

Update the application manifest

In your cumulocity.json file:

1. Add the required roles to be able to create events and alarms.
2. Add the readiness and liveness probes.
3. Add two keys for the microservice settings: "ipstack.key" and "tracker.id".
4. Set the isolation level to "PER_TENANT". This means that there will be a separate instance for each tenant. For more details see the Settings section in Microservice manifest.

Your manifest file should look similar to this:

{
    "apiVersion": "2",
    "version": "@project.version@",
    "provider": {
        "name": "Cumulocity"
    },
    "isolation": "PER_TENANT",
    "settings": [
        {
            "key": "ipstack.key",
            "defaultValue": "<your-ipstack-key>"
        },
        {
            "key": "tracker.id",
            "defaultValue": "<your-tracker-id>"
        }
    ],
    "livenessProbe": {
        "httpGet": {
            "path": "/health"
        },
        "initialDelaySeconds": 60,
        "periodSeconds": 10
    },
    "readinessProbe": {
        "httpGet": {
            "path": "/health",
            "port": 80
        },
        "initialDelaySeconds": 20,
        "periodSeconds": 10
    },
    "requiredRoles": [
        "ROLE_EVENT_READ",
        "ROLE_EVENT_ADMIN",
        "ROLE_ALARM_READ",
        "ROLE_ALARM_ADMIN"
    ],
    "roles": []
}

Creating a managed object

An alarm must be associated with a source and it requires an ID. Hence, you must create a managed object to be your source and use its ID in your microservice application. The same managed object will track the locations when the microservice gets accessed on a particular endpoint.

First, get your current location (latitude, longitude) using a free service, for example, My Current Location.

Create a managed object as a device named “Microservice tracker” via POST request as follows:

POST <URL>/inventory/managedObjects

HEADERS:
  Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json; charset=UTF-8; ver=0.9
  Accept: application/vnd.com.nsn.cumulocity.managedobject+json; charset=UTF-8; ver=0.9
  Authorization: <AUTHORIZATION>

BODY:
  {
    "c8y_IsDevice": {},
    "c8y_Position": {
      "lat": <LATITUDE>,
      "lng": <LONGITUDE>
    },
    "name": "Microservice tracker"
  }

You will get the ID of your managed object in the response. Assign this ID to the "tracker.id" key in your cumulocity.json file.

On the Cumulocity platform, navigate to Devices > All devices in the Device Management application to verify that your device has been created and its location is displayed on the map.

Getting the client’s location

The microservice will get the approximate location based on the client’s IP. To achieve this, it uses the free service ipstack and you must get a free API key. Once you have it, assign it to the "ipstack.key" key in your cumulocity.json file.

A GET request to the ipstack API using your key will return a location object. Therefore, you must create a new file named Location.java in the same directory of your App.java with the following content:

package c8y.example;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)
public class Location {

    private String city;
    private String country_code;
    private String latitude;
    private String longitude;

    public String getLongitude() {
        return longitude;
    }

    public void setLongitude(String longitude) {
        this.longitude = longitude;
    }

    public String getLatitude() {
        return latitude;
    }

    public void setLatitude(String latitude) {
        this.latitude = latitude;
    }

    public String getCountry_code() {
        return country_code;
    }

    public void setCountry_code(String country_code) {
        this.country_code = country_code;
    }

    public String getCity() {
        return city;
    }

    public void setCity(String city) {
        this.city = city;
    }
}

Updating the application

Modify your App.java file and:

1. Run the microservice as a Spring application.
2. Add a post-construct init method to get a subset of the environment variables and the microservice settings.
3. Add an event listener to the microservice subscription. Each time a tenant subscribes to the microservice, an alarm will be created.
4. Define a method to create LocationUpdate events based on the client’s IP.
5. Add the application endpoints.

Your code should look similar to:

package c8y.example;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;

import javax.annotation.PostConstruct;
import javax.servlet.http.HttpServletRequest;

import org.joda.time.DateTime;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.SpringApplication;
import org.springframework.context.event.EventListener;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;

import com.cumulocity.microservice.autoconfigure.MicroserviceApplication;
import com.cumulocity.microservice.context.ContextService;
import com.cumulocity.microservice.context.credentials.MicroserviceCredentials;
import com.cumulocity.microservice.settings.service.MicroserviceSettingsService;
import com.cumulocity.microservice.subscription.model.MicroserviceSubscriptionAddedEvent;
import com.cumulocity.model.idtype.GId;
import com.cumulocity.rest.representation.alarm.AlarmRepresentation;
import com.cumulocity.rest.representation.event.EventRepresentation;
import com.cumulocity.rest.representation.inventory.ManagedObjectRepresentation;
import com.cumulocity.sdk.client.Platform;
import com.cumulocity.sdk.client.event.EventFilter;

import net.minidev.json.JSONObject;

@MicroserviceApplication
@RestController
public class App {

    @Autowired
    private MicroserviceSettingsService settingsService;

    @Autowired
    private ContextService<MicroserviceCredentials> contextService;

    @Autowired
    private Platform platform;

    private Map<String, String> c8yEnv;

    public static void main (String[] args) {
        SpringApplication.run(App.class, args);
    }


    /**
    * Get some of the environment variables of the container and load the
    * microservice settings
    */
    @PostConstruct
    private void init () {
        // Environment variables
        var env = System.getenv();

        c8yEnv = new HashMap<>();
        c8yEnv.put("app.name", env.get("APPLICATION_NAME"));
        c8yEnv.put("url", env.get("C8Y_BASEURL"));
        c8yEnv.put("jdk", env.get("JAVA_VERSION"));
        c8yEnv.put("tenant", env.get("C8Y_TENANT"));
        c8yEnv.put("user", env.get("C8Y_USER"));
        c8yEnv.put("password", env.get("C8Y_PASSWORD"));
        c8yEnv.put("isolation", env.get("C8Y_MICROSERVICE_ISOLATION"));
        c8yEnv.put("memory.limit", env.get("MEMORY_LIMIT"));

        // Required ID and key
        c8yEnv.put("tracker.id", settingsService.get("tracker.id"));
        c8yEnv.put("ipstack.key", settingsService.get("ipstack.key"));
    }


    /**
    * Create a warning alarm on microservice subscription
    */
    @EventListener(MicroserviceSubscriptionAddedEvent.class)
    public void createAlarm (MicroserviceSubscriptionAddedEvent event) {
        contextService.callWithinContext(event.getCredentials(), () -> {
            var source = new ManagedObjectRepresentation();
            source.setId(GId.asGId(c8yEnv.get("tracker.id")));

            var alarm = new AlarmRepresentation();
            alarm.setSource(source);
            alarm.setSeverity("WARNING");
            alarm.setStatus("ACTIVE");
            alarm.setDateTime(DateTime.now());
            alarm.setType("c8y_Application__Microservice_subscribed");
            alarm.setText("The microservice " + c8yEnv.get("app.name") + " has been subscribed to tenant "
            + c8yEnv.get("tenant"));

            platform.getAlarmApi().create(alarm);

            return true;
        });
    }


    /**
    * Create a LocationUpdate event based on the client's IP
    *
    * @param String The public IP of the client
    * @return The created event
    */
    public EventRepresentation createLocationUpdateEvent (String ip) {
        // Get location details from ipstack
        var rest = new RestTemplate();
        var apiURL = "http://api.ipstack.com/" + ip + "?access_key=" + c8yEnv.get("ipstack.key");
        var location = rest.getForObject(apiURL, Location.class);

        // Prepare a LocationUpdate event using Cumulocity's API
        var c8y_Position = new JSONObject();
        c8y_Position.put("lat", location.getLatitude());
        c8y_Position.put("lng", location.getLongitude());

        var source = new ManagedObjectRepresentation();
        source.setId(GId.asGId(c8yEnv.get("tracker.id")));

        var event = new EventRepresentation();
        event.setSource(source);
        event.setType("c8y_LocationUpdate");
        event.setDateTime(DateTime.now());
        event.setText("Accessed from " + ip + " (" + (location.getCity() != null ? location.getCity() + ", " : "")
        + location.getCountry_code() + ")");
        event.setProperty("c8y_Position", c8y_Position);
        event.setProperty("ip", ip);

        // Create the event in the platform
        platform.getEventApi().create(event);

        return event;
    }


    /* * * * * * * * * * Application endpoints * * * * * * * * * */

    // Check the microservice status/health (implemented by default)
    // GET /health

    // Greeting endpoints
    @RequestMapping("hello")
    public String greeting (@RequestParam(value = "name", defaultValue = "World") String you) {
        return "Hello " + you + "!";
    }

    @RequestMapping("/")
    public String root () {
        return greeting("World");
    }

    // Return the environment values
    @RequestMapping("environment")
    public Map<String, String> environment () {
        return c8yEnv;
    }

    // Track client's approximate location
    @RequestMapping(value = "location/track", produces="application/json")
    public String trackLocation (HttpServletRequest request) {
        // Get the public IP address and create the event
        return createLocationUpdateEvent(request.getHeader("x-real-ip")).toJSON();
    }

    // Get the tracked IPs and locations
    @RequestMapping("location/locations")
    public ArrayList<Object> getLocations (@RequestParam(value = "max", defaultValue = "5") int max) {
        var filter = new EventFilter().byType("c8y_LocationUpdate");
        var locations = new ArrayList<Object>();
        var eventCollection = platform.getEventApi().getEventsByFilter(filter).get(max);

        eventCollection.getEvents().forEach((event) -> {
            var map = new HashMap<String, Object>();

            map.put("ip", event.getProperty("ip"));
            map.put("coordinates", event.getProperty("c8y_Position"));
            map.put("when", event.getCreationDateTime().toString("yyyy-MM-dd hh:mm:ss"));

            locations.add(map);
        });

        return locations;
    }
}

Building and deploying the application

Use the command mvn clean install and follow the same steps of the Hello world tutorial for Java to deploy your microservice. You may also employ the cURL command to deploy the microservice.

$ curl -F "data=@target/iptracker-microservice-1.0.0-SNAPSHOT.zip" \
     -H "Authorization: <AUTHORIZATION>" \
     "<URL>/application/applications/<APPLICATION_ID>/binaries"

Testing the application

You can test any endpoint of your application using the command line or a web browser. For example, a GET request to location/track will obtain the client’s IP from the request header and use the createLocationUpdateEvent method to get the approximate location. The response will be similar to:

{
  time: "2019-06-03T08:44:21.730Z",
    source: {
      id: "..."
    },
    text: "Accessed from ... (Sofia, BG)",
    type: "c8y_LocationUpdate",
    c8y_Position: {
      lng: "23.3175",
      lat: "42.683"
    },
    ip: "..."
}

Using the endpoint location/locations will return five stored events by default. You can use the max parameter to specify a higher number.

In the Device Management application, navigate to Devices > All devices and locate your microservice tracker. Under Tracking you will see a map with the tracked locations. You can also develop your own web application and customize a map widget. Refer to Application library.

Run the Docker container

The Docker image is built and added to the local Docker repository during the Maven build if the following property is set microservice.package.deleteImage=false. As you have learned in our Hello world tutorial for Java, you can run the Docker container locally. Note that in this case the isolation was changed to PER_TENANT. You can also use your Docker image name and tag to run it as follows:

$ docker run -p 8082:80 -e C8Y_BOOTSTRAP_TENANT=<BOOTSTRAP_USER_TENANT> -e C8Y_BOOTSTRAP_USER=<BOOTSTRAP_USER_NAME> -e C8Y_BOOTSTRAP_PASSWORD=<BOOTSTRAP_USER_PASSWORD> -e C8Y_MICROSERVICE_ISOLATION=PER_TENANT -i -t -e C8Y_BASEURL=<URL> iptracker-microservice:latest

If your Docker image has run successfully, you can test the microservice on any web browser. For instance, using http://localhost:8082/location/locations will return all the tracked locations.

Source code

The code of our iptracker-microservice can be found in our public GitHub repositories.

Developing microservices

See below for the different microservice SDK features, including annotations, services, configuration files, logging and the Maven build plugin.

There are two possible deployment types on the platform:

• Hosted deployment - The default for microservices and the suggested one for typical use cases.
• External/legacy deployment - Requires custom installation of the platform and agent.

For development and testing purposes, one can deploy a microservice on a local Docker container.

Annotations

The simplest way to add required behavior to your application is to annotate a main class with @MicroserviceApplication. This is a collective annotation consisting of:

Context support

The context support is covered by the annotation @EnableContextSupport. It allows to choose between @TenantScope and @UserScope which is related to the user management of microservices, as described in General aspects in Cumulocity.

Each microservice has a service user which can be used for the interaction with the platform. The roles associated with this user are specified in the manifest. Within the tenant scope, the credentials of this service user are used for the communication with the platform, while within the user scope the credentials of the authenticated user sending the request to the microservice are used.

Setting the context

You can explicitly set the context along with the credentials to be used through ContextService. To use the credentials of the user sending the request, use ContextService<UserCredentials>. Accordingly, ContextService<MicroserviceCredentials> can be used for service user credentials. Examples on how to use ContextService are given below.

@Autowired
private ContextService<UserCredentials> contextService;
@Autowired
private EventApi eventApi;

public PagedEventCollectionRepresentation get10Events () {
  return contextService.runWithinContext(contextService.getContext(), () -> eventApi.getEvents().get(10));
}

In this first example, the events are obtained using the credentials of the authenticated user.

In the second example, the credentials of the service user will be utilized to retrieve the events.

@Autowired
private ContextService<MicroserviceCredentials> contextService;
@Autowired
private EventApi eventApi;

public PagedEventCollectionRepresentation get10Events () {
  return contextService.runWithinContext(contextService.getContext(), () -> eventApi.getEvents().get(10));
}

Tenant scope

The tenant scope is associated with the usage of the service user credentials and is annotated with @TenantScope. To create a bean, named tenantEventApi in the tenant scope, use the annotation @TenantScope, as in the following code example.

@Autowired
private Platform platform;

@TenantScope
@Bean(name = "tenantEventApi")
public EventApi eventApi (Platform platform) throws SDKException {
  return platform.getEventApi();
}  

By default, the Platform API related beans provided by the Microservice SDK are created in the tenant scope and use the service user to communicate with the platform.

There are predefined beans both in the @TenantScope and @UserScope. The name of a bean in the tenant scope consists of the prefix "tenant" and the name of the respective API. Thus, to use the Event API in the tenant scope, you can specify @Qualifier(“tenantEventApi”), as shown in the example below. As the tenant scope is the default context for the created beans, the annotation can also be omitted. Therefore, the following two excerpts are equivalent and both suggest that the service user credentials will be used for the communication with the platform.

@Autowired
@Qualifier("tenantEventApi")
private EventApi eventApi;

@Autowired
private EventApi eventApi;

In both cases, beans within the tenant scope will be auto-wired.

User scope

In certain situations the microservice should not use the service user credentials but the credentials of the user sending the request.

To create a bean in the user scope, specify @UserScope:

@Autowired
private Platform platform;

@UserScope
@Bean(name = "userEventApi")
public EventApi eventApi (Platform platform) throws SDKException {
  return platform.getEventApi();
}  

Analogously to the tenant scope case, there are predefined beans in the user scope. The name of such beans consists of the prefix “user” and the name of the API. An example of auto-wiring a bean of the @UserScope is given below.

@Autowired
@Qualifier("userEventApi")
private EventApi eventApi;

Within the user scope, the created beans use the credentials of the authenticated user sending the request instead of the default service user for the communication with the platform.

Microservice security

The @EnableMicroserviceSecurity annotation sets up the standard security configuration for microservices. It requires basic authorization for all endpoints (except for health check endpoint configured using @EnableHealthIndicator). A developer can secure its endpoints using standard Spring security annotations, for example, @PreAuthorize("hasRole('ROLE_A')") and user’s permissions will be validated against user’s roles stored on the platform.

Microservice subscription

The microservice subscription module is responsible for two main features:

• Registration
• Tenant subscription event listening

The default behavior for the package is self-registration, which means that after you run the application it will try to register and use the generated credentials for the communication with the platform. The self-registration is required to correctly deploy the microservice on the platform.

The other way to register an application to the platform is to do it manually. This can be done by creating a new application on the platform with the same application name and providing the following properties into the microservice:

application.name=<application_name>
C8Y.bootstrap.register=false
C8Y.bootstrap.tenant=<tenant>
C8Y.bootstrap.user=<username>
C8Y.bootstrap.password=<password>

To create an application and acquire credentials, refer to Creating applications and Acquiring microservice credentials in the Using the REST interface section.

The subscription package provides means to monitor and it acts upon changes in tenant subscriptions to a microservice. To add a custom behavior, a developer can add an event listener for MicroserviceSubscriptionAddedEvent and MicroserviceSubscriptionRemovedEvent as the following example:

@EventListener
public void onAdded (MicroserviceSubscriptionAddedEvent event {
    log.info("subscription added for tenant: " + event.getCredentials().getTenant());
});

On application startup, the MicroserviceSubscriptionAddedEvent is triggered for all subscribed tenants.

Heap and perm/metadata

To calculate heap and perm/metadata, it takes the limit defined on the microservice manifest and it is converted into Megabytes (MB). For Java applications developed using the Java Microservice SDK the minimal value is 178MB.
10% is reserved for “system”, but not less than 50 MB.
10% is taken for Metaspace, but not less than 64 MB and not more than 1024MB.
The rest is allocated for heap size.

Platform API

The package consists of a number of services that are built and injected into Spring context. A developer can use them to perform basic operations against the platform. The beans are built based on the properties read from a file. For hosted deployment, most of the properties are provided by the platform.

The API provides the following services:

• Alarm - AlarmApi
• AuditRecord - AuditRecordApi
• Operation - DeviceControlApi
• Event - EventApi
• ExternalID - IdentityApi
• Binary - BinariesApi
• ManagedObject - InventoryApi
• Measurement - MeasurementApi

The API provides basic CRUD methods. The following is an alarm interface example:

// Methods
AlarmRepresentation create(final AlarmRepresentation alarm)
Future createAsync(final AlarmRepresentation alarm)

AlarmRepresentation getAlarm(final GId gid)
AlarmCollection getAlarms()
AlarmCollection getAlarmsByFilter(final AlarmFilter filter)

AlarmRepresentation update(final AlarmRepresentation alarm)

Sample usage:

@Autowired
private AlarmApi alarms;

public AlarmRepresentation addHelloAlarm (){
    AlarmRepresentation alarm = new AlarmRepresentation();
    alarm.setSeverity("CRITICAL");
    alarm.setStatus("Hello");

    return alarms.create(alarm);
}

Configuration files

The application.properties file used by the hosted deployment must be located in src/main/resources/.

The following properties are used by a microservice:

General properties

HTTP client configuration properties

Microservice settings

The microservice settings module provides two features:

• Configure a microservice by defining tenant options
• Override existing properties - Tenant options can override default values from properties files

By default the microservice loads the tenant options for the category specified by the microservice context path. The custom settings category can be specified by the manifest parameter: settingsCategory. When neither settings category nor context path is provided in the microservice manifest, the application name is used.

Options can be configured for the application owner or the subscriber. The subscriber can override the owner’s option value only when such option is defined as editable.

Settings are lazy cached for 10 minutes, so when they were accessed previously, the user must wait the remaining time to see the change being applied. When the access attempt occurs to fetch settings without the tenant context being specified, the application owner is used to complete the request.

Tenant option settings can be accessed in two ways:

Using Environment:

@Autowired
private Environment environment;  

public int getAccessTimeout() {
    return environment.getProperty("access.timeout", Integer.class, 30);
}

Using settings service:

@Autowired
private MicroserviceSettingsService settingsService;

public String getAccessTimeout() {
    return settingsService.get("access.timeout");
}

Settings can be encrypted by using the credentials. prefix for the tenant option key. They will be decrypted and become available within the microservice environment.

Defining tenant options for a microservice with the same key as it was defined in the configuration files, such as .properties or the manifest file, will override the particular property.

For instance, there is a property defined in the application.properties file of the microservice hello-world with context path helloworld:

access.timeout=25

Now the microservice owner can override it by defining the following setting in the cumulocity.json manifest file:

"settings": [{
    "key": "access.timeout",
    "defaultValue": "35",
    "editable": true
}]

Because the access.timeout setting is defined as editable, the subscriber can override it by creating an own tenant option via REST API:

POST <URL>/tenant/options

BODY:
  {
    "category": "helloworld",
    "key": "access.timeout",
    "value": "40"
  }

Logging

The standard output should be used for hosted deployment.

Maven plugin

The package module provides a Maven plugin to prepare a ZIP file required by the microservice deployment. The build requires an executable JAR file. To create one, a developer can use spring-boot-maven-plugin. An example with minimum configuration is presented below:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>repackage</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <mainClass>${main.class}</mainClass>
    </configuration>
</plugin>
<plugin>
    <groupId>com.nsn.cumulocity.clients-java</groupId>
    <artifactId>microservice-package-maven-plugin</artifactId>
    <version>${c8y.version}</version>
    <executions>
        <execution>
            <id>package</id>
            <phase>package</phase>
            <goals>
              <goal>package</goal>
            </goals>
            <configuration>
              <name>hello-world</name>
              <encoding>UTF-8</encoding>
              <rpmSkip>true</rpmSkip>
              <containerSkip>false</containerSkip>
            </configuration>
        </execution>
        <execution>
            <id>microservice-package</id>
            <phase>package</phase>
            <goals>
              <goal>microservice-package</goal>
            </goals>
            <configuration>
              <name>hello-world</name>
              <image>hello-world</image>
              <encoding>UTF-8</encoding>
              <skip>false</skip>
            </configuration>
        </execution>
    </executions>
</plugin>

Package goal

The package plugin is responsible for the creation of a Docker container, rpm file and for creating a ZIP file that can be deployed on the platform. It can be configured with the following parameters:

• name (alias package.name) - defaults to project.artifactId
• description (alias package.description) - defaults to project.description
• jvmArgs (alias agent-package.jvmArgs) - jvm-gc arguments. The default value is -XX:+UseG1GC -XX:+UseStringDeduplication -XX:MinHeapFreeRatio=25 -XX:MaxHeapFreeRatio=75. It will be overwritten if other options are provided
• arguments (alias agent-package.arguments) - arguments passed during application startup
• encoding (alias project.build.sourceEncoding) - defaults to UTF-8
• heap (alias agent-package.heap) - defaults to min = 128MB max = 384MB
• perm (alias agent-package.perm) - defaults to min = 64MB max = 128MB
• skip (alias skip.agent.package) - to skip the whole packaging part
• rpmSkip (alias skip.agent.package.rpm) - to skip rpm file creation. False by default
• containerSkip (alias skip.agent.package.container) - to skip Docker image creation. True by default
• manifestFile - points to a manifest file location. Default value: $/src/main/configuration/cumulocity.json
• dockerBuildTimeout - specifies the timeout in seconds for the docker image build. Defaults to 360s

Example configuration:

<configuration>
    <name>hello-world</name>
    <encoding>UTF-8</encoding>
    <rpmSkip>true</rpmSkip>
    <containerSkip>false</containerSkip>
    <manifestFile>${basedir}/src/main/microservice/cumulocity.json</manifestFile>
</configuration>

Push goal

The push plugin is responsible for pushing the Docker image to a registry. The registry can be configured by:

• containerSkip (alias skip.agent.package.container) - Prevents the push to execute. True by default
• registry (alias agent-package.container.registry) - Docker registry address

Example configuration:

<configuration>
    <registry>http://{yourregistry.com}</registry>
    <containerSkip>false</containerSkip>
</configuration>

Upload goal

The upload goal is responsible for deploying the microservice to a server. There are three options to configure the server URL and credentials:

• settings.xml - Maven global configuration placed at ~/.m2/settings.xml
• pom.xml - Maven project configuration file
• Command line

All three ways can be used together, for example, a goal partially can be configured in the settings.xml and partially in the pom.xml. In case of conflicts, the command line configuration has the highest priority and settings.xml configuration the lowest.

To upload a microservice to the server you must configure the following properties:

• url - Mandatory URL that will be used for deployment. Empty by default.
• username - Mandatory tenant ID and username used for authorization. Empty by default.
• password - Mandatory password used for authorization. Empty by default.
• name - Optional name of the uploaded application. By default it is the same as package.name property or artifactId if package.name is not provided.
• skipMicroserviceUpload (alias skip.microservice.upload) - Controls if the microservice upload should be skipped. True by default so for the goal to work it must be set to false)

settings.xml

To configure the goal in the settings.xml file, add the server configuration as follows:

<server>
    <id>microservice</id>
    <username>demos/username</username>
    <password>******</password>
    <configuration>
        <url>https://demos.cumulocity.com</url>
    </configuration>
</server>

pom.xml

To configure the plugin in the pom.xml file, add the server configuration as follows:

<plugin>
    <groupId>com.nsn.cumulocity.clients-java</groupId>
    <artifactId>microservice-package-maven-plugin</artifactId>
    <configuration>
        <application>
            <name>helloworld</name>
        </application>

        <!-- please note that the credentials are optional if they are already configured in settings.xml -->
        <credentials>
            <url>https://demos.cumulocity.com</url>
            <username>demos/username</username>
            <password>******</password>
        </credentials>

        <skipMicroserviceUpload>false</skipMicroserviceUpload>
    </configuration>
</plugin>

Command line

To pass the configuration only to the particular build, execute the following command:

$ mvn microservice:upload -Dupload.application.name=helloworld -Dupload.url=https://demos.cumulocity.com -Dupload.username=demos/username -Dupload.password=****** -Dskip.microservice.upload=false

Deployment

Hosted deployment

To deploy an application on an environment you need the following:

• URL address of your tenant
• Authorization header as “Basic <Base64(:)>”
• Tenant - tenant ID
• ZIP build from previous steps

Step 1 - Create the application

If the application does not exist, create a new application on the platform:

POST /application/applications
Host: ...
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: "application/json"

BODY:
  {
		"name": "<APPLICATION_NAME>",
		"type": "MICROSERVICE",
		"key": "<APPLICATION_NAME>-microservice-key"
  }

Example:

$ curl -X POST -s \
      -d '{"name":"hello-microservice-1","type":"MICROSERVICE","key":"hello-microservice-1-key"}' \
      -H "Authorization: <AUTHORIZATION>" \
      -H "Content-type: application/json" \
      "<URL>/application/applications"

If the application has been created correctly, you can GET the application ID:

GET /application/applicationsByName/<APPLICATION_NAME>
Host: ...
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Accept: "application/json"

Example:

$ curl -H "Authorization:<AUTHORIZATION>" \
     <URL>/application/applicationsByName/hello-world

Step 2 - Upload the ZIP file

POST /application/applications/<APPLICATION_ID>/binaries
Host: ...
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: "multipart/form-data"

Example:

$ curl -F "data=@<PATH_TO_ZIP>" \
	     -H "Authorization: <AUTHORIZATION>" \
	     "<URL>/application/applications/<APPLICATION_ID>/binaries"

Step 3 - Subscribe to the microservice

POST /tenant/tenants/<TENANT_ID>/applications
Host: ...
Authorization: Basic xxxxxxxxxxxxxxxxxxx
Content-Type: "multipart/form-data"

BODY:
  {
    "application": {
        "id": "<APPLICATION_ID>"
    }
  }

Example:

$ curl -X POST -d '{"application":{"id": "<APPLICATION_ID>"}}'  \
       -H "Authorization: <AUTHORIZATION>" \
       -H "Content-type: application/json" \
       "<URL>/tenant/tenants/<TENANT_ID>/applications"

Local Docker deployment

To deploy the application on a local Docker container, one must inject the environment variables into a container. This is done with the Docker run -e command. The full description of available parameters is available in Environment variables.

An example execution could be:

$ docker run -e "C8Y_BASEURL=<C8Y_BASEURL>" -e "C8Y_BASEURL_MQTT=<C8Y_BASEURL_MQTT>" <IMAGE_NAME>

Monitoring

The microservice’s health endpoint can be checked to verify if a hosted microservice is running successfully. This endpoint is enabled by default for all microservices that are developed using the Java Microservice SDK.

GET <URL>/service/<APPLICATION_NAME>/health

Example response when the microservice is functional:

HTTP/1.1 200
{
  "status": "UP"
}

or in case it is not working:

HTTP/1.1 503
{
  "status": "DOWN"
}

Legacy Deployment

Properties

For external/legacy deployment, the following paths will be searched in order to find a properties file specific for the environment the application is run on:

• {UPPERCASE(application_name)}_CONF_DIR/.{application_name}
• {UPPERCASE(application_name)}_CONF_DIR/{application_name}
• {user/home}/.{application_name}
• {user/home}/{application_name}
• {CONF_DIR}/.{application_name}
• {CONF_DIR}/{application_name}
• /etc/{application_name}

Logging

For external/legacy deployment, logging into the application implies using Spring Logging. The following locations are searched for the Logback configuration file:

• {UPPERCASE(application_name)}_CONF_DIR/.{application_name}/logging.xml
• {UPPERCASE(application_name)}_CONF_DIR/{application_name}/logging.xml
• {user/home}/.{application_name}/logging.xml
• {user/home}/{application_name}/logging.xml
• {CONF_DIR}/.{application_name}/logging.xml
• {CONF_DIR}/{application_name}/logging.xml
• /etc/{application_name}/logging.xml

Upgrade to Microservice SDK 10.13+

A Spring Boot library was upgraded to 2.5.8, hence upgrading Microservice SDK to 10.13+ may require some additional development.

• The content(matcher) method of RestAssured has been replaced with body(matcher), see RequestSpecification#content()

• Spring Boot BOM does not define a version for joda-time, you may need to explicitly define version.

  Maven example:

  <dependency>
    <groupId>joda-time</groupId>
    <artifactId>joda-time</artifactId>
    <version>2.10.10</version>
  </dependency>
  

• Jackson 2.12.x does not provide the Joda Module by default, it might be required to add jackson-datatype-joda dependency and define Joda Module: new ObjectMapper().addModule(new JodaModule()); in a custom Microservice code.

• Spring Boot 2.5.8 does not provide the Bean Validation 2.0 provider as a transitive dependency anymore. Developers may have to explicitly define a validation provider, for example hibernate-validator, or add the spring-boot-starter-validation dependency.

  Maven example:

  <dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-validation</artifactId>
  </dependency>
  

• junit-vintage-engine was removed from the spring-boot-starter-test dependency, if you still use JUnit 4.x you must add the Vintage engine explicitly:

  <dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <scope>test</scope>
  </dependency>
  

• The message field and binding errors are disabled by default for Spring Boot native error responses. This can be enabled by overriding the microservice_error_attributes.properties file.

  Sample content:

  server.error.include-message=ALWAYS
  server.error.include-binding-errors=ALWAYS
  

Upgrade to Microservice SDK 10.17+

A Spring Boot library was upgraded to 2.7.6, hence upgrading Microservice SDK to 10.17+ may require some additional development.

There was a change in the internal microservice security configuration following the deprecation of WebSecurityConfigurerAdapter by Spring Security. The Microservice SDK now uses a direct declaration of the SecurityFilterChain bean in its internal configuration instead. At the same time, Spring Security only allows one of these configuration approaches in a single application. This means that if the old, adapter-based method has been used in your code before, you will have to migrate to the new, direct filters declaration for applications to start. Refer to the Spring Security documentation for more details.

Client library

This section provides an overview on how to access Cumulocity from Java clients, starting from connecting to the platform over accessing data to remote control of devices. It also discusses how to extend the Cumulocity domain model from Java for new devices and other business objects. Finally, this section describes how to configure the logging service in order to control the level of diagnostic messages generated by the client.

The client library is tightly linked to the design of the REST interfaces, which are described in REST implementation in the Cumulocity OpenAPI Specification.

Connecting to the platform

The root interface for connecting to Cumulocity from Java is called Platform (see Root interface in REST implementation in the Cumulocity OpenAPI Specification). It provides access to all other interfaces of the platform, such as the inventory. In its simplest form, it is instantiated as follows:

Platform platform = new PlatformImpl("<URL>", new CumulocityCredentials("<USERNAME>", "<PASSWORD>"));

As an example:

Platform platform = new PlatformImpl("https://demos.cumulocity.com", new CumulocityCredentials("myuser", "mypassword"));

If you use the Java client for developing an application, you must register an application key (through Managing applications in the Cumulocity Administration application, or through the Application API).

For testing purposes, every tenant is subscribed to the demo application key “uL27no8nhvLlYmW1JIK1CA==”. The constructor for PlatformImpl also allows you to specify the default number of objects returned from the server in one reply with the parameter pageSize.

new CumulocityCredentials("<TENANT_ID>", "<USERNAME>", "<PASSWORD>", "<APPLICATION_KEY>")

Accessing the inventory

The following code snippet shows how to obtain a handle to the inventory:

InventoryApi inventory = platform.getInventoryApi();

Using this handle, you can create, retrieve and update managed objects. For example, if you would like to retrieve all objects that have a geographical position, use the following:

InventoryFilter inventoryFilter = new InventoryFilter();
inventoryFilter.byFragmentType(Position.class);
ManagedObjectCollection moc = inventory.getManagedObjectsByFilter(inventoryFilter);

Note that it returns a query to get the objects but it does not actually get them. In practice, such a list of objects could be very large. Hence, it is returned in pages from the server. To get all pages and iterate over them, use the following:

for (ManagedObjectRepresentation mo : moc.get().allPages()) {
	System.out.println(mo.getName());
}

To create a new managed object, construct a local representation of the object and send it to the platform. The following code snippet shows how to create a new electricity meter with a relay in it:

ManagedObjectRepresentation mo = new ManagedObjectRepresentation();
mo.setName("MyMeter-1");

Relay relay = new Relay();
mo.set(relay);

SinglePhaseElectricitySensor meter = new SinglePhaseElectricitySensor();
mo.set(meter);

// Set additional properties, for example, tariff tables
mo = inventory.create(mo);
System.out.println(mo.getId());

By invoking the create() method, a new managed object is created with an auto-generated unique identifier.

Assume that you would like to store additional custom properties along with the device. This can be done by creating a new fragment in the form of a Java bean. For example, assume that you would like to store tariff information along with your meter. There is a day and a night time tariff, and you must store the hours during which the night time tariff is active:

public class Tariff {
    public int getNightTariffStart() {
        return nightTariffStart;
    }

    public void setNightTariffStart(int nightTariffStart) {
        this.nightTariffStart = nightTariffStart;
    }

    public int getNightTariffEnd() {
        return nightTariffEnd;
    }

    public void setNightTariffEnd(int nightTariffEnd) {
        this.nightTariffEnd = nightTariffEnd;
    }

    private int nightTariffStart = 22;
    private int nightTariffEnd = 6;
}

Now, you can add the tariff information to your meter:

Tariff tariff = new Tariff();
mo.set(tariff);

Accessing the identity service

A device typically has a technical identifier that an agent must know to be able to contact the device. Examples are meter numbers, IP addresses and REST URLs. To associate such identifiers with the unique identifier of Cumulocity, agents can use the identity service. Again, to create the association, create an object of type ExternalIDRepresentation and send it to the platform.

The code snippet below shows how to register a REST URL for a device. It assumes that mo is the managed object from the above example and deviceUrl is a string with the REST URL of the device.

final String ASSET_TYPE = "com_cumulocity_idtype_AssetTag";
final String deviceUrl = "SAMPLE-A-239239232";

ExternalIDRepresentation externalIDGid = new ExternalIDRepresentation();
externalIDGid.setType(ASSET_TYPE);
externalIDGid.setExternalId(deviceUrl);
externalIDGid.setManagedObject(mo);

IdentityApi identityApi= platform.getIdentityApi();
identityApi.create(externalIDGid);

Now, if you need the association back, you can just query the identity service as follows:

ID id = new ID();
id.setType(ASSET_TYPE);
id.setValue(deviceUrl);
externalIDGid = identityApi.getExternalId(id);

The returned object will contain the unique identifier and a link to the managed object.

Accessing events and measurements

Events and measurements can be accessed in a very similar manner as described above for the inventory. The following example queries the signal strength of the mobile connection of devices in the past two weeks and prints the device ID, the time of the measurement, the received signal strength and the bit error rate.

MeasurementApi measurementApi = platform.getMeasurementApi();
MeasurementFilter measurementFilter = new MeasurementFilter();

Calendar cal = Calendar.getInstance();
Date toDate = cal.getTime();
cal.add(Calendar.DATE, -14);

Date fromDate = cal.getTime();
measurementFilter.byDate(fromDate, toDate);
measurementFilter.byFragmentType(SignalStrength.class);

MeasurementCollection mc = measurementApi.getMeasurementsByFilter(measurementFilter);
MeasurementCollectionRepresentation measurements = mc.get();

for (; measurements != null; measurements = mc.getNextPage(measurements)) {
	for (MeasurementRepresentation measurement : measurements.getMeasurements()) {
		SignalStrength signal = measurement.get(SignalStrength.class);
		System.out.println(measurement.getSource().getId() + " " + measurement.getTime() + " " + signal.getRssiValue() + " " + signal.getBerValue());
	}
}

Controlling devices

The DeviceControlResource enables you to manipulate devices remotely. It has two sides: You can create operations in applications to be sent to devices, and you can query operations from agents.

In order to control a device it must be in the child devices hierarchy of an agent managed object. The agent managed object represents your agent in the inventory. It is identified by a fragment com_cumulocity_model_Agent. This is how Cumulocity identifies where to send operations to control a particular device.

The following code demonstrates the setup:

ManagedObjectRepresentation agent = new ManagedObjectRepresentation();
agent.set(new com.cumulocity.model.Agent()); // agents must include this fragment

// ... create agent in inventory
ManagedObjectRepresentation device;

// ... create device in inventory
ManagedObjectReferenceRepresentation child2Ref = new ManagedObjectReferenceRepresentation();
child2Ref.setManagedObject(device);
inventory.getManagedObject(agent.getId()). addChildDevice(child2Ref);

For example, assume that you would like to switch off a relay in a meter from an application. Similar to the previous examples, you create the operation to be executed locally, and then send it to the platform:

DeviceControlApi control = platform.getDeviceControlApi();
OperationRepresentation operation = new OperationRepresentation();

operation.setDeviceId(mo.getId());
relay.setRelayState(RelayState.OPEN);
operation.set(relay);
control.create(operation);

Now, if you want to query the pending operations from an agent, the following code must be executed:

OperationFilter operationFilter = new OperationFilter();
operationFilter.byAgent(mo.getId().getValue());
operationFilter.byStatus(OperationStatus.PENDING);
OperationCollection oc = control.getOperationsByFilter(operationFilter);

Again, the returned result may come in several pages due to its potential size.

OperationCollectionRepresentation opCollectionRepresentation;

for (opCollectionRepresentation = oc.get(); opCollectionRepresentation != null; opCollectionRepresentation = oc.getNextPage(opCollectionRepresentation)) {
	for (OperationRepresentation op : opCollectionRepresentation.getOperations()) {
		System.out.println(op.getStatus());
	}
}

Realtime features

The Java client libraries fully support the real-time APIs of Cumulocity. For example, to get immediately notified when someone sends an operation to your agent, use the following code:

Subscriber<GId, OperationRepresentation> subscriber = deviceControl.getNotificationsSubscriber();
Subscription<> subscription = subscriber.subscribe(agentId, new SubscriptionListener<GId, OperationRepresentation> {

    public void onError(Subscription<GId> sub, Throwable e) {
		logger.error("OperationDispatcher error!", e);
	}

	public void onNotification(Subscription<GId> sub, OperationRepresentation operation) {
		// Execute the operation
	}
});

To unsubscribe from a subscription, use the following code:

subscription.unsubscribe();

If you wish to disconnect, the following code must be used:

subscriber.disconnect();

Subscribing to Notifications 2.0

The Notifications 2.0 API can be accessed in a very similar manner as described above in Accessing the inventory. See Notifications 2.0 for more details about the API.

The following snippet shows how users can create, query and delete notification subscriptions. It also shows how a token string can be obtained.

// Obtain a handle to the Subscription and Token APIs:
private final NotificationSubscriptionApi notificationSubscriptionApi = platform.getNotificationSubscriptionApi();
private final TokenApi tokenApi = platform.getTokenApi();

// Create subscription filter
final NotificationSubscriptionFilterRepresentation filterRepresentation = new NotificationSubscriptionFilterRepresentation();
filterRepresentation.setApis(List.of("measurements"));
filterRepresentation.setTypeFilter("c8y_Speed");

// Construct subscription for managed object context
final NotificationSubscriptionRepresentation subscriptionRepresentation1 = new NotificationSubscriptionRepresentation();
subscriptionRepresentation1.setContext("mo");
subscriptionRepresentation1.setSubscription("testSubscription1");
subscriptionRepresentation1.setSource(mo);
subscriptionRepresentation1.setSubscriptionFilter(filterRepresentation);
subscriptionRepresentation1.setFragmentsToCopy(List.of("c8y_SpeedMeasurement", "c8y_MaxSpeedMeasurement"));

// Create subscription for managed object context
subscriptionApi.subscribe(subscriptionRepresentation1);

// Construct subscription for tenant context
final NotificationSubscriptionRepresentation subscriptionRepresentation2 = new NotificationSubscriptionRepresentation();
subscriptionRepresentation2.setContext("tenant");
subscriptionRepresentation2.setSubscription("testSubscription2");

// Create subscription for tenant context
subscriptionApi.subscribe(subscriptionRepresentation2);

// Obtain access token
final NotificationTokenRequestRepresentation tokenRequestRepresentation = new NotificationTokenRequestRepresentation(
        properties.getSubscriber(), // The subscriber name with which the client wishes to be identified.
        "testSubscription1",        // The subscription name. This value should be the same as with which the subscription was created. The access token will be only valid for the subscription specified here.
        1440,                       // The token expiration duration in minutes.
        false);

// The obtained token is required for establishing a WebSocket connection. Refer to [Notifications 2.0](https://cumulocity.com/api/core/#tag/Notification-2.0-API) for more details.
final String token = tokenApi.create(tokenRequestRepresentation).getTokenString();

// Query all subscriptions
final NotificationSubscriptionCollection notificationSubscriptionCollection = subscriptionApi.getSubscriptions();
final List<NotificationSubscriptionRepresentation> subscriptions = notificationSubscriptionCollection.get().getSubscriptions();

for (NotificationSubscriptionRepresentation subscriptionRepresentation : subscriptions) {
    System.out.println(subscriptionRepresentation);
}

// Query subscriptions by filter
final NotificationSubscriptionCollection filteredNotificationSubscriptionCollection = subscriptionApi
        .getSubscriptionsByFilter(new NotificationSubscriptionFilter().byContext("mo"));
final List<NotificationSubscriptionRepresentation> filteredSubscriptions = filteredNotificationSubscriptionCollection.get().getSubscriptions();

for (NotificationSubscriptionRepresentation subscriptionRepresentation : filteredSubscriptions) {
    System.out.println(subscriptionRepresentation);
}

// Delete all tenant subscriptions
subscriptionApi.deleteTenantSubscriptions();

// Delete by source
subscriptionApi.deleteBySource(mo.getId().getValue());

There is a sample microservice available in the cumulocity-examples repository with more details on the API usage.

Reliability features

In particular on mobile devices, Internet connectivity might be unreliable. To support such environments, the Java client libraries support local buffering. This means that you can pass data to the client libraries regardless of an Internet connection being available or not. If a connection is available, the data will be sent immediately. If not, the data will be buffered until the connection is back again. For this, asynchronous variants of the API calls are offered. For example, to send an alarm:

AlarmApi alarmApi = platform.getAlarmApi();
Future future = alarmApi.createAsync(anAlarm);

The createAsync method returns immediately. The Future object can be used to determine the result of the request whenever it was actually carried out.

Logging configuration

Logging in the Java client SDK is handled through slf4j with a logback backend. For a detailed description on how to use and configure logging, see the logback documentation.

Since version 10.11, the default logging level of the SDK is set to “Error” for all components, which means that logging messages are suppressed unless their level is “Error”. If everything runs smoothly, there should be no log messages generated by the SDK. By default, log messages are sent to the console only.

The default logging configuration can be changed by providing a new configuration file. Two methods for providing the configuration file are discussed here: via an absolute filename passed using a system property; and via an OSGi fragment. Note that both of these methods override the default behaviour, rather than extending it.

Services platform and SMS API

This section describes the Cumulocity SMS API and shows how to access it using the Cumulocity Java Client. You will also learn how to send and receive SMS messages via the Java Client API.

Using the services platform

The services platform interface is responsible for connecting to the Java services (SMS) API.

ServicesPlatform platform = new ServicesPlatformImpl("<URL>", new CumulocityCredentials("<tenant>", "<user>", "<password>", "<application key>"));

The URL pointing to the platform must be of the form <tenant>.cumulocity.com, for example https://demos.cumulocity.com, which will process all the API requests.

Accessing the SMS Messaging API

The following code snippet shows how to obtain a handle to the SMS API from Java.

SmsMessagingApi smsMessagingApi = platform.getSmsMessagingApi();

Using this handle, you can send and retrieve the SMS messages from Java by calling its functions.

Assigning required roles

To use the SMS messaging API, the user must have the required roles SMS_ADMIN and SMS_READ for sending and receiving messages respectively. Refer to Managing permissions for more information.

Sending a message

To send a SMS message using the API, prepare the message with the SendMessageRequest builder and call the sendMessage function of the API with the prepared message.

SendMessageRequest smsMessage = SendMessageRequest.builder()
        .withSender(Address.phoneNumber("<phone number>"))
        .withReceiver(Address.phoneNumber("<phone number>"))
        .withMessage("<message text>")
        .build();

smsMessagingApi.sendMessage(smsMessage);

Receiving messages

You can use the API as follows to receive all SMS messages. Note that not every SMS provider supports receiving messages.

smsMessagingApi.getAllMessages(Address.phoneNumber("<phone number>"));

You can use the API as follows to receive a specific SMS message identified by message ID. Note that not every SMS provider supports receiving messages.

smsMessagingApi.getMessage(Address.phoneNumber("<phone number>"), "<message id>");

SMS management endpoints

The REST API can be used to send and receive SMS messages.

Sending a message:

POST /service/messaging/smsmessaging/outbound/tel:<sender phone number>/requests
Host: ...
Authorization: Basic ...
Content-Type: application/json
{
    "outboundSMSMessageRequest": {
        "address": ["tel:<phone number>"],
        "senderAddress": "tel:<phone number>",
        "outboundSMSTextMessage": {
  	       "message": "<message text>"
        },
        "receiptRequest": {
  	       "notifyUrl": "<notify url>",
  	        "callbackData": "<callback data>"
        },
        "senderName": "<sender name>"
    }
}

Receiving all messages:

GET /service/messaging/smsmessaging/inbound/registrations/tel:<receiver phone number>/messages
Host: ...
Authorization: Basic ...

HTTP/1.1 200 OK
{
     "inboundSMSMessageList": [
        {
            "inboundSMSMessage": {
            "dateTime": "<date>",
            "destinationAddress": "<destination address>",
            "messageId": "<message id>",
            "message": "<message>",
            "resourceURL": "<resource url>",
            "senderAddress": "<sender address>"
        }
     ]
}

Receiving a specific message:

GET /service/messaging/smsmessaging/inbound/registrations/tel:<receiver phone number>/messages/<message id>
Host: ...
Authorization: Basic ...

HTTP/1.1 200 OK
{
    "inboundSMSMessage": {
        "dateTime": "<date>",
        "destinationAddress": "<destination address>",
        "messageId": "<message id>",
        "message": "<message>",
        "resourceURL": "<resource url>",
        "senderAddress": "<sender address>"
    }
}

Troubleshooting

Some common problems and their solutions have been identified and documented below.

SSL or certificate errors

You can use both HTTP and HTTPS from the Java client libraries. To use HTTPS, you may need to import the Cumulocity production certificate into your Java Runtime Environment. Download the certificate with the following command:

$ echo | openssl s_client -servername *.cumulocity.com -connect *.cumulocity.com:443 |sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cumulocity.com.crt

Import the certificate using the following command:

$ $JAVA_HOME/bin/keytool -import -alias cumulocity -file cumulocity.com.crt -storepass changeit

Confirm that you trust this certificate.

Use the following argument to run Java:

-Djavax.net.ssl.trustStore=<home directory>/.keystore

If you use Eclipse/OSGi, open the Run Configurations… dialog in the Run menu. Double-click OSGi Framework, then open the Arguments tab on the right side. In the VM arguments text box, add the above parameter.

Since the Java SDK comes with its own set of trusted root certificates, you might still get the error message “java.security.cert.CertificateException: Certificate Not Trusted”. In this case, make sure that the GoDaddy Certificate Authority (CACert) is available for your Java environment using the following command:

$ keytool -import -v -trustcacerts -alias root -file gd_bundle.crt -keystore $JAVA_HOME/lib/security/cacerts

The gd_bundle.crt certificate can be downloaded directly from the GoDaddy repository.

When I install the SDK, Eclipse complains about compatibility problems

Make sure that you use the Target Platform preferences page to install the SDK as described in the instructions. Install New Software installs software into your running Eclipse IDE, but you must install the SDK as a separate server software.

I get “Expected to find an object at table index” when running a microservice or application

This error occurs due to a bug in particular Eclipse versions. As a workaround, select Run from the main menu and then Run Configurations …. On the left, select the launch configuration that you have been using, for example, OSGi Framework. On the right, click the Arguments tab. Append a " -clean" to the Program Arguments and click Apply.

The microservice or application won’t start

Verify that all required plug-ins are checked in your launch configuration. Go to Run > Run Configurations and select the OSGi Framework launch configuration. Click Select All and try running it again.

Check if the required plug-ins are started. While the application or microservice is running, type “ss” into the console and hit the return key. All listed plug-ins should be either in the ACTIVE or RESOLVED state.

Check if you are using the correct target platform. Go to the Target Platform page in the preferences and check if “Cumulocity runtime” is checked.

The microservice application does not compile. I get “Access Restriction” messages

This error may be caused because of a missing package import. Navigate to the Dependencies tab of the project manifest file and check if the package of the type that contains the method giving the access restriction is present in the Import-Package section.

You can find the package by opening the declaration of the method (right-click and select Open Declaration from the context menu).

When starting an application I get “address already in use” messages

Check if you are running another instance of the application. Click on the Display Selected Console icon in the console toolbar (the terminal icon) to browse through your consoles. Terminate other running instances by clicking the red Stop icon in the toolbar.

Under Unix/macOS you can also use the lsof command to see which process is using a particular port. For example, to see which process is using TCP port 8080 enter:

$ lsof -i tcp:8080

It will return something like:

COMMAND    PID  USER  FD   TYPE      DEVICE  SIZE/OFF  NODE  NAME
java     12985   neo  45u  IPv6  0x077c76d0       0t0   TCP  *:8080 (LISTEN)

This means that the process 12985 is using the 8080 port and it can be killed if necessary.

When trying to build an application I get a “BeanCreationException: Error creating bean with name methodSecurityInterceptor” error

This is caused mainly by versions incompatibility between the SDK and Spring Boot specified in your pom.xml file. If you want to use a recent version of the SDK, for example, 1016.0.0, the version of Spring Boot must be compatible or equal to version 2.5.4.

Missing Docker permissions in Linux

When you build a microservice application via mvn, you might get this error:

[ERROR] Failed to execute goal com.nsn.cumulocity.clients-java:microservice-package-maven-plugin:1004.6.12:package (package) on project hello-microservice-java: Execution package of goal com.nsn.cumulocity.clients-java:microservice-package-maven-plugin:1004.6.12:package failed: org.apache.maven.plugin.MojoExecutionException: Exception caught: java.util.concurrent.ExecutionException: com.spotify.docker.client.shaded.javax.ws.rs.ProcessingException: java.io.IOException: Permission denied -> [Help 1]

This is an issue with Docker in Linux OS. You can verify that your user is lacking permissions for Docker by running:

$ docker ps
Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.40/containers/json: dial unix /var/run/docker.sock: connect: permission denied

In order to fix this, do the following:

1. Create the Docker group.

   $ sudo groupadd docker
   

2. Add your user to the Docker group.

   $ sudo usermod -aG docker $your_user_name
   

3. Log out and log back in, so that your group membership is updated. Alternatively, run

   $ newgrp docker
   

4. Try running a Docker command again.

Also refer to Docker Engine > Installation per distro > Optional post-installation steps in the Docker documentation.