HTTP Device Factory

Eclipse sensiNact provides an HTTP device factory: HTTP requests can be sent at regular intervals and their content handled by the device factory core.

Bundles

The HTTP device factory is provided by: org.eclipse.sensinact.gateway.southbound.http:http-device-factory:0.0.2.

It relies on the device factory and on the Eclipse Jetty client and therefore requires the following bundles:

  • org.eclipse.sensinact.gateway.southbound.device-factory:device-factory-core:0.0.2

  • org.eclipse.jetty:jetty-util:11.0.13

  • org.eclipse.jetty:jetty-io:11.0.13

  • org.eclipse.jetty:jetty-alpn-client:11.0.13

  • org.eclipse.jetty:jetty-client:11.0.13

Note that the device factory also requires parsers to work.

Configuration

The HTTP device factory waits for configurations with PID sensinact.http.device.factory.

The configuration can describe “one-shot” and “periodic” tasks. One-shot tasks will be executed when the configuration is created or updated. They can be used to load the static description of providers, e.g. the location of a bus stop.

Here are the available configuration options:

  • mapping: the device factory mapping configuration (mandatory)

  • url: target URL (mandatory)

  • timeout: HTTP request timeout, in seconds (30s by default)

  • bufferSize: maximum size of the response payload, in kilo-bytes (512B minimum)

  • method: HTTP method/verb to use (GET by default)

  • headers: HTTP request headers

  • http.followRedirect: follow the HTTP redirection responses (3xx)

  • auth.user: basic authentication login

  • auth.password: basic authentication password

  • ssl.ignoreErrors: ignore SSL errors

  • ssl.keystore: path to the SSL key store

  • ssl.keystore.password: password of the SSL key store

  • ssl.truststore: path to the SSL trust store

  • ssl.truststore.password: password of the SSL trust store

Periodic tasks use the same configuration as one-shot tasks, with the additional options:

  • period: number of “period units” to wait between requests

  • period.unit: the unit of time of the “period” entry, as the name of a java.time.temporal.ChronoUnit constant. Defaults to seconds.

Here is an example of configuration for HTTP device factory that will get the description of cycling stations using a one-shot request, while updating their status every minute:

{
  "tasks.oneshot": [
    {
      "url": "xxx-opendata.xxx.pro/opendata/cycling/station_information.json",
      "mapping": {
        "parser": "json",
        "parser.options": {
          "base": "data/stations"
        },
        "mapping": {
          "$station_id": "station_id",
          "@provider": {
            "literal": "cycling-${station_id}"
          },
          "@name": "name",
          "@latitude": "lat",
          "@longitude": "lon",
          "station/capacity": "capacity"
        }
      }
    }
  ],
  "tasks.periodic": [
    {
      "period": 60,
      "url": "https://xxx-opendata.xxx.pro/opendata/cycling/station_status.json",
      "mapping": {
        "parser": "json",
        "parser.options": {
          "base": "data/stations"
        },
        "mapping": {
          "$station_id": "station_id",
          "@provider": {
            "literal": "cycling-${station_id}"
          },
          "station/active": "is_installed",
          "station/stationCode": "stationCode",
          "cycling/docks_available": "num_docks_available",
          "cycling/bikes_available": "num_bikes_available"
        }
      }
    }
  ]
}

Important notes:

  • the order of execution of the requests is not defined.

  • avoid periodic tasks with a period less than a second (and be nice to the servers).

Context variables

The HTTP device factory provides the HTTP response headers as context variables to the device factory. The device factory core will prefix them automatically with $context..

For example, the response content type will be available in the mapping variables as ${context.Content-Type}.