/
How to use Spring client library, aka Client4SpringBoot?

How to use Spring client library, aka Client4SpringBoot?

Introduction

The platform offers several modules allow for the acquisition of information, mostly API Manager and DigitalBroker (also known as IoTBroker).

The API Manager allows you to easily, visually publish access (queries, updates, insertions) to ontologies such as REST APIs offering OpenAPI interfaces (swagger), so that you can create a client in any technology to attack these APIs.

You can see how to use the API Manager in any of these tutorials:

(API Manager) Creación y Ciclo de vida de las APIs / (API Manager) Invocación a APIS vía Swagger y generación de cliente con Swagger Editor / (API Manager) Invocar APIs de gestión de la plataforma con Token OAuth2

Using the API Manager has several advantages, such as having a record and catalogue of the interfaces (the services) published by the system for client consumption.

But there are scenarios where the API Manager approach may not be the most suitable, for instance:

  • If I am working in Java with Spring Boot and I don't want to generate many wrappers for the published APIs.

  • If I am using the platform as a data repository and I have a great number of ontologies to deal with.

  • If I need more flexibility and reduced development times.

  • If I am a device and I want to use a more efficient protocol such as MQTT.

In these and many other scenarios, you may be more interested in using the DigitalBroker as your business' input point.

What is Client4SpringBoot?

Client4SpringBoot is a Java library designed to work on Spring Boot and that simplifies access to DigitalBroker by wrapping the queries with a Repository interface that allows you invoke the DigitalBroker using Java methods.

Let's see what it looks like:

The way to access the ontologies is through an interface where the queries on the DigitalBroker are defined:

then I configure connection with the DigitalBroker and, through Spring's dependences injection, I can use this Repository to access the DigitalBroker. 


How can I use it?

Let's see how you can use Client4SpringBoot with an example. In the example, you will do this:

  • You will create an example ontology, e.g. an ontology to represent an incidence reported by a citizen in a city (CitizenTicket) and a connection with the Platform (Token,...)

  • You will create a Maven project and configure it with the library so you can communicate with the platform, inserting and recovering data to and from the previously created ontology.

Let's go!!!

Accessing the Environment and creating the Ontology and the DigitalClient for the example

  1. Let's start by connecting to one of the Environments' Control Panel in the Platform. For this example, you will use the experimentation environment we enabled: https://lab.onesaitplatform.com/controlpanel/
    If you don't have a user yet, you can create it directly by clicking New Account.
    Once in the ControlPanel you can start working. Log in and go to the menu option: My Ontologies:


    Select CREATE to create a new ontology. In this case, select Creation Step by Step:

    although you could also choose loading data from a file.

    In this example, you will create the ontology with this data: 


    Remember that the ontology name is unique, so that your Ontology must include something making it unique such as: CitizenTicket_<iduser>
    Now select a base template to create the ontology. In the example, select GENERAL's EmptyBase:
    This template has no base attribute, so that you can create your ontology as you want.
    Click ADD NEW PROPERTY to add your properties:

     
    In the example, create these attributes:

  •  

    • mail: String required (it represent the person's contact e-mail).

    • explanation: String required (it represents the incidence's description).

    • status: String required (the incidence's status; when just registered, it is PENDING).

    • coordinates: GeoJSON Point type optional (coordinates where the incidence was registered).

    • fullName: String optional (full name of the incidence's sender).

It looks like this in the Control Panel:

Next click on the button . This updates the JSON-Schema, that internally represents the ontology, and you can edit it in:

In the window appearing now, select

to see the JSON-Schema and, in this case, to replace the root element, currently EmptyBase, with something more descriptive such as CitizenTicket:

You can click

to get an idea on how's the JSON structure you must send to the platform from your client:

Save this example, as it will be useful later:

{"CitizenTicket":{ "mail":"string","explanation":"string","status":"string","coordinates":{"coordinates":[28.6,28.6],"type":"Point"},"fullName":"string"}}

You'll end your ontology creation by clicking on the

button.

Bear in mind you have generated an ontology with default configuration, that is to say, authorizing no other user and using MongoDB as the storage database. This can be configured in the AUTHORIZATIONS and ADVANCED SETTINGS tabs.



2. Once the ontology is created, the System allows you to create an API for this ontology, a Device, a gadget or a Dashboard.

In this case, select Create new Device

This will take you directly to the Create Client screen:

In this screen, you must give your client an identification, for example ClientCitizenTicket_lmgracia, and you must also specify that it works with your ontology, CitizenTicket_lmgracia, with access level: All.