The Raptor Java SDK is part of the raptor platform and used extensively in the codebase.
It can be reused as a standalone library in external application for a direct integration to the exposed API
- Java 8 or higher
- Maven
Import in your project the raptor-sdk
maven package.
Let's start by initializing a raptor client instance
// login with username and password
Raptor raptor = new Raptor("http://raptor.local", "admin", "admin")
// alternatively, login with a token
// Raptor raptor = new Raptor("http://raptor.local", "..token..")
// login and retrieve a token
AuthClient.LoginState loginInfo = raptor.Auth().login();
log.debug("Welcome {} (token: {})", loginInfo.user.getUsername(), loginInfo.token);
// close the session and drop the login token
raptor.Auth().logout();
The inventory API store device definitions
List devices owned by a user
List<Device> list = raptor.Inventory().list();
log.debug("found {} devices", list.size());
Create a new device definition
Device dev = new Device();
dev.name("test device")
.description("info about");
dev.properties().put("active", true);
dev.properties().put("cost", 15000L);
dev.properties().put("version", "4.0.0");
dev.validate();
raptor.Inventory().create(dev);
log.debug("Device created {}", dev.id());
Update a device definition
// Create a data stream named ambient with a channel temperature of type number
Stream s = dev.addStream("ambient", "temperature", "number");
//Add further channels of different types
s.addChannel("info", "text")
s.addChannel("alarm", "boolean")
// add an action
Action a = dev.addAction("light-control");
raptor.Inventory().update(dev);
log.debug("Device updated: \n {}", dev.toJSON());
Load a device definition
Device dev1 = raptor.Inventory().load(dev.id());
log.debug("Device loaded: \n {}", dev.toJSON());
Search for device definitions
DeviceQuery q = new DeviceQuery();
// all devices which name contains `test`
q.name.contains("test");
// and properties.version equals to 4.0.0
q.properties.has("version", "4.0.0");
log.debug("Searching for {}", q.toJSON().toString());
List<Device> results = raptor.Inventory().search(q);
log.debug("Results found {}", results.stream().map(d -> d.name()).collect(Collectors.toList()));
When a device receive data, an action is triggered or the definition changes events are emitted over an asynchronous MQTT channel.
Device events are notified when a device definition changes
raptor.Inventory().subscribe(dev, new DeviceCallback() {
@Override
public void callback(Device obj, DevicePayload message) {
log.debug("Device event received {}", message.toString());
}
});
Data events are generated when a stream is updated
raptor.Inventory().subscribe(dev, new DataCallback() {
@Override
public void callback(Stream stream, RecordSet record) {
log.debug("dev: Data received {}", record.toJson());
}
});
Action events are generated when an action is triggered or the status changes
raptor.Inventory().subscribe(dev, new ActionCallback() {
@Override
public void callback(Action action, ActionPayload payload) {
log.debug("dev: Data received for {}: {}",
payload.actionId,
payload.data
);
}
});
The Stream API handles data push and retrieval
Send data based on a stream definition
Stream stream = dev.getStream("ambient")
RecordSet record = new RecordSet(stream)
.channel("temperature", 5)
.channel("info", "cold")
.channel("alarm", true)
.location(new GeoJsonPoint(11, 45))
.timestamp(Instant.now())
;
raptor.Stream().push(record)
Retrieve data
// return 100 records from 10
int from = 10,
size = 100;
ResultSet results = raptor.Stream().pull(stream, from, size);
Retrieve the last record sent based on the timestamp
ResultSet results = raptor.Stream().lastUpdate(stream);
Removed the data stored in a stream
raptor.Stream().delete(stream);
Search for a range in the data timestamp
Instant i = Instant.now()
DataQuery q = new DataQuery()
.timeRange(
i.plus(500, ChronoUnit.MILLIS),
i.plus(2500, ChronoUnit.MILLIS)
);
log.debug("Searching {}", q.toJSON().toString());
ResultSet results = raptor.Stream().search(stream, q);
Search for a range in a numeric field
DataQuery q = new DataQuery()
.range("temperature", -10, 10);
log.debug("Searching {}", q.toJSON().toString());
ResultSet results = raptor.Stream().search(stream, q);
Search data by distance using the location
field
DataQuery q = new DataQuery()
.distance(new GeoJsonPoint(11.45, 45.11), 10000, Metrics.KILOMETERS);
log.debug("Searching {}", q.toJSON().toString());
ResultSet results = raptor.Stream().search(stream, q);
Search data within an area using the location
field
DataQuery q = new DataQuery()
.boundingBox(new GeoJsonPoint(12, 45), new GeoJsonPoint(10, 44)));
log.debug("Searching {}", q.toJSON().toString());
ResultSet results = raptor.Stream().search(stream, q);
The Action API handles status and triggering of device defined actions
Store the current status of an action
Action a = dev.action("light-control");
ActionStatus status = raptor.Action()
.setStatus(a, a.getStatus().status("on"));
Get the current stored status of an action
Action a = dev.action("light-control");
ActionStatus status = raptor.Action()
.getStatus(a);
Trigger an action on the remote device
Action a = dev.action("light-control");
ActionStatus status = raptor.Action()
.invoke(a);
Set the status of an action
The Profile API handles a per-user key-value local store
Set a value by key
ObjectNode json = r.Profile().newObjectNode();
json.put("test", "foo");
json.put("size", 1000L);
json.put("valid", true);
r.Profile().set("test1", json);
Get a value by key
JsonNode response = r.Profile().get("test1");
Get all values
JsonNode response = r.Profile().get();
The Tree API handles hierarchical data structures
Create a generic (type group
) node tree
TreeNode node1 = TreeNode.create("Root1");
raptor.Tree().create(node1);
TreeNode child1 = TreeNode.create("child1");
TreeNode child2 = TreeNode.create("child2");
raptor.Tree().add(node1, Arrays.asList(child1));
raptor.Tree().add(child1, Arrays.asList(child2));
Create a device references inside the tree. Events from that device will be propagated to the parent nodes up to the root
raptor.Tree().add(child2, dev);
List all the trees available
List<TreeNode> list = raptor.Tree().list();
Delete a node, causing all the leaves to be point to the parent. In case of device
node references, this will not remove the device
// drop child1 from previous example, child2 will be now direct children of Root1
raptor.Tree().remove(
node1 //Root1
.children().get(0) // child1
);
Admin APIs allow the management of users, tokens and permissions
For an up to date reference see the tests
Apache2
Copyright FBK/CREATE-NET
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.