README.md

FIWARE NGSI API

This project is a Java library for the NGSI v2 API

This library was originally created for the Fiware-Cepheus project. A library implementing NGSI v1 API can be found at Orange-OpenSource/fiware-ngsi-api

What remains to be done:

• Simplified Entity Representation.
• Virtual Attribute.
• NotifyContext.
• NotifyContextAvailability.

Usage

Client

The client is based on Spring AsyncRestTemplate HTTP client.

Add the client library to your pom.xml:

<dependency>
    <groupId>com.orange.fiware</groupId>
    <artifactId>ngsi2-client</artifactId>
    <version>X.Y.Z</version>
</dependency>

Get an instance of NgsiClient and provide the AsyncRestTemplate (a default one or customized to your needs) and a base URL for the NGSIv2 server to target:

AsyncRestTemplate asyncRestTemplate = new AsyncRestTemplate();
String baseURL = "http://server.org/";
Ngsi2Client client = new Ngsi2Client(asyncRestTemplate, baseURL);

All requests return a ListenableFuture. You can therefore block to get the response or provide a callback:

// Synchronous
Entity entity = ngsiClient.getEntity("DC_S1-D41", "Room", Arrays.asList("temperature", "humidity")).get();

// Asynchronous
ngsiClient.getEntity("DC_S1-D41", "Room", Arrays.asList("temperature", "humidity")).addCallback(entity -> {
        /* handle entity */
    }, ex -> {
        /* handle error */
    });

Request returning a list of elements (entities, types, etc...) use a Paginated class that wraps the list of elements and return additional pagination information like offet, limit and total count of elements:

// List the first twenty types and count total types
Paginated<EntityType> result = ngsiClient.getEntityTypes(0, 20, true).get();

List<EntityType> types = result.getItems();
int total = result.getTotal();

Server

The library proposes an abstract class Ngsi2BaseController based on the Spring MVC framework to let you implement a NGSIv2 server easily.

Add the server library to your pom.xml:

<dependency>
    <groupId>com.orange.fiware</groupId>
    <artifactId>ngsi2-server</artifactId>
    <version>X.Y.Z</version>
</dependency>

Implement a new class based on the Ngsi2BaseController in your project and override methods you want to support :

@RestController
@RequestMapping("/v2/")
public class Ngsi2Controller extends Ngsi2BaseController {
    @Override
    protected void createEntity(Entity entity){
      /* implementation */
    }
}

License

This project is under the Apache License version 2.0