This library makes it possible to create jvm enabled device or coap based services. It can also help to emulate an embedded device for prototyping and testing purposes.
The following features are supported by the library:
This project started as a fork from https://github.com/PelionIoT/java-coap, but it has changed significantly, so it became project of its own.
Add to your build.gradle.kts
dependencies {
...
implementation("io.github.open-coap:coap-core:VERSION")
implementation("io.github.open-coap:coap-mbedtls:VERSION") // for DTLS support
implementation("io.github.open-coap:coap-tcp:VERSION") // for coap over tcp support
implementation("io.github.open-coap:coap-metrics:VERSION") // for micrometer integration
implementation("io.github.open-coap:coap-netty:VERSION") // for netty integration
}
Add dependency into your pom.xml
:
<dependency>
<groupId>io.github.open-coap</groupId>
<artifactId>coap-core</artifactId>
<version>{VERSION}</version>
</dependency>
// build CoapClient that connects to coap server which is running on port 5683
CoapClient client = CoapServer.builder()
.transport(udp())
.buildClient(new InetSocketAddress("localhost", 5683));
// send request
CoapResponse resp = client.sendSync(CoapRequest.get("/sensors/temperature"));
LOGGER.info(resp.toString());
client.close();
// build CoapClient that connects to coap server which is running on port 5683
client = CoapServer.builder()
// define transport, plain text UDP listening on random port
.transport(udp())
// (optional) register observation listener to handle incoming observations
.notificationsReceiver((resourceUriPath, observation) -> {
LOGGER.info("Observation: {}", observation);
// in case of block transfer, call to retrieve rest of payload
CompletableFuture<Opaque> payload = retrieveRemainingBlocks(resourceUriPath, observation, req -> client.send(req));
return true; // return false to terminate observation
})
// (optional) set custom observation relation store, for example one that will use external storage
.observationsStore(new HashMapObservationsStore())
// (optional) define maximum block size
.blockSize(BlockSize.S_1024)
// (optional) set maximum response timeout, default for every request
.responseTimeout(Duration.ofMinutes(2))
// (optional) set maximum allowed resource size
.maxIncomingBlockTransferSize(1000_0000)
// (optional) set extra filters (interceptors) to outbound pipeline
.outboundFilter(
// each request will be set with different Token
TokenGeneratorFilter.sequential(1)
)
// build client with target server address
.buildClient(new InetSocketAddress("localhost", 5683));
// send ping
client.ping();
// send request
CompletableFuture<CoapResponse> futureResponse = client.send(CoapRequest.get("/sensors/temperature"));
futureResponse.thenAccept(resp ->
// .. handle response
LOGGER.info(resp.toString())
);
// send request with payload and header options
CompletableFuture<CoapResponse> futureResponse2 = client.send(CoapRequest
.post("/actuator/switch")
// set header options, for example:
.options(opt -> opt
.etag(Opaque.decodeHex("0a8120"))
.accept(MediaTypes.CT_APPLICATION_JSON)
.maxAge(Duration.ofHours(1))
)
.payload("{\"power\": \"on\"}", MediaTypes.CT_APPLICATION_JSON)
.addContext(TransportContext.RESPONSE_TIMEOUT, Duration.ofMinutes(3)) // overwrite default response timeout
);
futureResponse2.thenAccept(resp ->
// .. handle response
LOGGER.info(resp.toString())
);
// observe (subscribe) to a resource, observations will be handled by observation listener
CompletableFuture<CoapResponse> resp3 = client.send(CoapRequest.observe("/sensors/temperature"));
LOGGER.info(resp3.join().toString());
client.close();
// define subscription manager for observable resources
ObserversManager observersManager = new ObserversManager();
server = CoapServer.builder()
// configure with plain text UDP transport, listening on port 5683
.transport(new DatagramSocketTransport(5683))
// define routing
// (note that each resource function is a `Service` type and can be decorated/transformed with `Filter`)
.route(RouterService.builder()
.get("/.well-known/core", req ->
CoapResponse.ok("</sensors/temperature>", MediaTypes.CT_APPLICATION_LINK__FORMAT).toFuture()
)
.post("/actuators/switch", req -> {
// ...
return coapResponse(Code.C204_CHANGED).toFuture();
})
// observable resource
.get("/sensors/temperature", observersManager.then(req ->
CoapResponse.ok("21C").toFuture()
))
)
.build();
observersManager.init(server);
server.start();
All requests are handled by implementing Service<REQ, RES>
interface, which is a simple function:
(REQ) -> CompletableFuture<RES>
Intercepting is achieved by implementing Filter
interface, which is again a simple function:
(REQ, Service<IN_REQ, IN_RES>) -> CompletableFuture<RES>
Filter interface has a set of helper functions to compose with another Filter
and Service
.
Together it creates a pipeline of request handling functions.
It is following "server as a function" design concept. It is a very simple, flexible and testable way to model data processing in a pipeline. It is best describe in this white paper: Your Server as a Function, and has a great implementation in Finagle project.
Every Service
implementation can be decorated with Filter
. It can be used to implement any kind of authorisation, authentication, validation, rate limitations etc.
For example, if we want to limit allowed payload size, it could be done:
MaxAllowedEntityFilter filter = new MaxAllowedEntityFilter(100, "too big")
Service<CoapRequest, CoapResponse> filteredRoute = filter.then(route)
Another example, is to use auto generated etag
for responses and validate it in requests:
EtagGeneratorFilter filter2 = new EtagGeneratorFilter()
EtagValidatorFilter filter3 = new EtagValidatorFilter()
Service<CoapRequest, CoapResponse> filteredRoute = filter3.andThen(filter2).then(route)
All request handling filters are under package ..coap.server.filter.
This coap-cli module provides command line utility.
./gradlew build
build./gradlew publishToMavenLocal
publish to local maven./gradlew dependencyUpdates
determine which dependencies have updates./gradlew useLatestVersions
update dependencies to the latest available versions./gradlew wrapper --gradle-version VERSION
Upgrading the Wrapper versionAll contributions are Apache 2.0. Only submit contributions where you have authored all of the code. If you do this on work time make sure your employer is OK with this.
Unless specifically indicated otherwise in a file, files are licensed under the Apache 2.0 license, as can be found in: LICENSE