README.md

FIWARE NGSI v1 API

This project is the library of the NGSI v1 API

This library was originally created for the Fiware-Cepheus project and the original version is still available here under the GPLv2 Licence.

A library implementing NGSI v2 API can be found at Orange-OpenSource/fiware-ngsi2-api

Usage

From Maven

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

For java 7, you must add the classifier:

<dependency>
   <groupId>com.orange.fiware</groupId>
   <artifactId>ngsi-client</artifactId>
   <classifier>java7</classifier>
    <version>X.Y.Z</version>
</dependency>
<dependency>
   <groupId>com.orange.fiware</groupId>
   <artifactId>ngsi-server</artifactId>
   <classifier>java7</classifier>
    <version>X.Y.Z</version>
</dependency>

where X.Y.Z is the version of the library to use (check git tags).

Download the jar from Sonatype Central repository using wget

If you don't have maven installed on your machine, you can still download the standalone JAR using wget or any browser:

wget -O ngsi-client.jar "https://oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots&g=com.orange.fiware&a=ngsi-client&v=LATEST"
wget -O ngsi-server.jar "https://oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots&g=com.orange.fiware&a=ngsi-server&v=LATEST"

Client

The implementation provides the NgsiClient class for the standard operations and the NgsiRestClient` class for the convenient REST operations.

The client uses ListenableFuture to handle requests synchronously or asynchronously.

Example: to send a synchronous updateContext

    @Autowired
    NgsiClient ngsiClient;

    /* [...] */

    UpdateContext update = new UpdateContext();
    // [...] add context information

    ngsiClient.updateContext(providerUrl, httpHeaders, update).get();

Example: to send an asynchronous updateContext

    ngsiClient.updateContext(brokerUrl, httpHeaders, update)
              .addCallback(updateContextResponse -> logUpdateContextResponse(updateContextResponse, brokerUrl),
                       throwable -> logger.warn("UpdateContext failed for {}", brokerUrl, throwable));

Server

The implementation provides the NgsiBaseController class that is a controller class for the standard operations and the NgsiRestBaseController class used for the convenient REST operations. The two classes validate the specification rules and return errors if an exception is thrown.

Your controller class must override the methods you want to implement. By default the methods return an error "not implemented operation".

    public class MyNgsiController extends NgsiBaseController {
        @Override
        public UpdateContextResponse updateContext(final UpdateContext update) throws Exception {
            // implement updateContext
        }
    }

and

    public class NgsiRestController extends NgsiRestBaseController {
        @Override
        protected AppendContextElementResponse appendContextElement(String entityID, AppendContextElement appendContextElement) throws Exception {
                    // implement appendContextElement
        }
    }

License

This project is under the Apache License version 2.0