Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/FraunhoferIOSB/FROST-Client
Library implementing a client interface to the SensorThingsAPI
https://github.com/FraunhoferIOSB/FROST-Client
Last synced: 3 months ago
JSON representation
Library implementing a client interface to the SensorThingsAPI
- Host: GitHub
- URL: https://github.com/FraunhoferIOSB/FROST-Client
- Owner: FraunhoferIOSB
- License: mit
- Fork: true (nsommer/SensorThingsClient)
- Created: 2016-07-30T17:44:08.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-06-24T17:57:00.000Z (5 months ago)
- Last Synced: 2024-06-27T19:53:11.065Z (5 months ago)
- Language: Java
- Size: 553 KB
- Stars: 28
- Watchers: 9
- Forks: 13
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-sensorthings-api - Frost-Client - based client library for the SensorThingsAPI and aims to simplify development of SensorThings enabled client applications. (Tools / Example Query)
README
# Frost-Client [](https://github.com/FraunhoferIOSB/FROST-Client/actions) [](https://codecov.io/gh/FraunhoferIOSB/FROST-Client) [](https://www.codacy.com/gh/FraunhoferIOSB/FROST-Client?utm_source=github.com&utm_medium=referral&utm_content=FraunhoferIOSB/FROST-Client&utm_campaign=Badge_Grade)
The **FR**aunhofer **O**pensource **S**ensor**T**hings-Client is a Java-based client
library for the [SensorThingsAPI](https://github.com/opengeospatial/sensorthings) and
aims to simplify development of SensorThings enabled client applications.
## Features
* CRUD operations
* Queries on entity sets
* Loading of referenced entities
* MultiDatastreams
* dataArray (for creating observations)
## Unsupported
* Batch requests
* dataArray (for requesting observations)
* MQTT
## Using with maven
Add the dependency:
```xml
de.fraunhofer.iosb.ilt
FROST-Client
0.45
```
## Using with gradle
Add the dependency:
```gradle
compile 'de.fraunhofer.iosb.ilt:FROST-Client:0.45'
```
## API
The `SensorThingsService` class is central to the library. An instance of it represents a SensorThings service and is identified by an URI.
### CRUD operations
The source code below demonstrates the CRUD operations for Thing objects. Operations for other entities work similarly.
```java
URL serviceEndpoint = new URL("http://example.org/v1.1/");
SensorThingsService service = new SensorThingsService(serviceEndpoint);
```
```java
Thing thing = ThingBuilder.builder()
.name("Thingything")
.description("I'm a thing!")
.build();
service.create(thing);
// get Thing with numeric id 1234
thing = service.things().find(1234l);
// get Thing with String id ab12cd
thing = service.things().find("ab12cd");
thing.setDescription("Things change...");
service.update(thing);
service.delete(thing);
```
### Entity Sets
Entity Sets are represented by instances of `EntityList<>`. The query parameters specified by the SensorThingsAPI standard can be applied to queries.
```java
EntityList things = service.things()
.query()
.count()
.orderBy("description")
.select("name","id","description")
.filter("")
.expand()
.skip(5)
.top(10)
.list();
for (Thing thing : things) {
System.out.println("So many things!");
}
```
Entity sets only load so many entities at a time. If you want to get *all* entities,
and there are more entities than the $top parameter allows you get in one request, you can
use the `EntityList.fullIterator();` Iterator.
```java
EntityList observations = service.observations()
.query()
.count()
.top(1000)
.list();
Iterator i = observations.fullIterator();
while (i.hasNext()) {
Observation obs = i.next();
System.out.println("Observation " + obs.getId() + " has result " + obs.getResult());
}
```
Related entity sets can also be queried.
```java
// Get the thing with ID 1
thing = service.things().find(1l);
// Get the Datastreams of this Thing
EntityList dataStreams = thing.datastreams().query().list();
for (Datastream dataStream : dataStreams) {
Sensor sensor = dataStream.getSensor();
System.out.println("dataStream " + dataStream.getId() + " has Sensor " + sensor.getId());
}
```
### Loading referenced objects
Loading referenced objects in one operation (and therefore in one request) is supported. The *$expand* option of the SensorThingsAPI standard is used internally.
```java
Thing thing = service.things().find(1l,
Expansion.of(EntityType.THING)
.with(ExpandedEntity.from(EntityType.LOCATIONS)));
EntityList locations = thing.getLocations();
```
Or using a simple string to define the expand:
```java
EntityList things = service.things().query()
.expand("Locations($select=name,encodingType,location)")
.list();
for (Iterator it = things.fullIterator(); it.hasNext();) {
Thing thing = it.next();
EntityList locations = thing.getLocations();
}
```
### DataArray for Observation creation
Using DataArrays for creating Observations is more efficient, since only one http request
is done, and the observations are more efficiently encoded in this request, so the request
is smaller than the sum of the separate, normal requests.
```java
Set properties = new HashSet<>();
properties.add(DataArrayValue.Property.Result);
properties.add(DataArrayValue.Property.PhenomenonTime);
DataArrayValue dav1 = new DataArrayValue(datastream1, properties);
dav1.addObservation(observation1);
dav1.addObservation(observation2);
dav1.addObservation(observation3);
DataArrayValue dav2 = new DataArrayValue(multiDatastream1, properties);
dav2.addObservation(observation4);
dav2.addObservation(observation5);
dav2.addObservation(observation6);
DataArrayDocument dad = new DataArrayDocument();
dad.addDataArrayValue(dav1);
dad.addDataArrayValue(dav2);
service.create(dad);
```
### Subscription via MQTT
To be notified about changes to entities or entity sets you can use MQTT subscriptions.
```java
// subscribe directly to an entity, topic: [version]/Datastreams(1)
MqttSubscription datastreamDirectSubscription = DatastreamBuilder
.builder()
.service(service)
.id(new IdLong(1L))
.build()
.subscribe(x -> System.out.println(x.getId()));
service.unsubscribe(datastreamDirectSubscription);
// subscribe to an entity relative to another, topic: [version]/Datastreams(1)/Thing
MqttSubscription thingViaDatastreamSubscription = DatastreamBuilder
.builder()
.service(service)
.id(new IdLong(1L))
.build()
.subscribeRelative(x -> System.out.println(x.getId()), EntityType.THING);
service.unsubscribe(thingViaDatastreamSubscription);
// subscribe directly to an entity set, topic: [version]/Observations
MqttSubscription observationsDirectSubscription = service
.observations()
.subscribe(x -> System.out.println(x.getId()));
service.unsubscribe(observationsDirectSubscription);
// subscribe directly to an entity set including only selected properties in the response,
// topic: [version]/Observations?$select=result,resultTime
MqttSubscription observationsDirectWithSelectSubscription = service
.observations()
.subscribe(x -> System.out.println(x.getId()), EntityProperty.RESULT, EntityProperty.RESULTTIME);
service.unsubscribe(observationsDirectWithSelectSubscription);
// subscribe directly to an entity set but locally filter incoming notifications before calling the handler function
// here: only fire handler if observation was man since yesterday
MqttSubscription observationsDirectWithFilterSubscription = service
.observations()
.subscribe(x -> x.getResultTime().isAfter(ZonedDateTime.now().minusDays(1)),
x -> System.out.println(x.getId()),
EntityProperty.RESULT, EntityProperty.RESULTTIME);
service.unsubscribe(observationsDirectWithFilterSubscription);
// subscribe to an entity relative to another, topic: [version]/Datastreams(1)/Observations
MqttSubscription observationsViaDatastreamSubscription = DatastreamBuilder
.builder()
.service(service)
.id(new IdLong(1L))
.build()
.subscribeRelative(x -> System.out.println(x.getId()), EntityType.OBSERVATIONS);
service.unsubscribe(observationsViaDatastreamSubscription);
```
## Background
This library emerged from a practical work for a lecture at [KIT](http://www.kit.edu) in collaboration with the [Fraunhofer IOSB](http://iosb.fraunhofer.de). A [server implementation](https://github.com/FraunhoferIOSB/FROST-Server) of the SensorThingsAPI, developed by the Fraunhofer IOSB, is available on GitHub as well.
## Contributing
Contributions are welcome!
1. Fork this repository
2. Commit your changes
3. Create a pull request
## License
The code and the documentation of this work is available under the MIT license.