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:
- Complete CoAP support
- CoRE Link Format processing API
- Constrained RESTful Environments (CoRE) Link Format RFC 6690
- CoAP server mode
- CoAP client mode
- Coap over tcp, tls RFC 8323
- excluding: websockets, observations with BERT blocks
- Network transports:
- UDP (plain text)
- TCP (plain text)
- DTLS 1.2 with CID (using mbedtls)
- X509 Certificate
- PSK
- TLS
- LwM2M TLV and JSON data formats
- JRE 8, 11, 17
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
}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
CoapClient client = CoapServer.builder()
// define transport, plain text UDP listening on random port
.transport(udp())
// (optional) define maximum block size
.blockSize(BlockSize.S_1024)
// (optional) set maximum response timeout
.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")
.options(opt -> {
// set header options, for example:
opt.setEtag(Opaque.decodeHex("0a8120"));
opt.setAccept(MediaTypes.CT_APPLICATION_JSON);
opt.setMaxAge(3600L);
})
.payload("{\"power\": \"on\"}", MediaTypes.CT_APPLICATION_JSON)
);
futureResponse2.thenAccept(resp ->
// .. handle response
LOGGER.info(resp.toString())
);
// observe resource (subscribe), observations will be handled to provided callback
CompletableFuture<CoapResponse> resp3 = client.observe("/sensors/temperature", coapResponse -> {
LOGGER.info(coapResponse.toString());
return true; // return false to terminate observation
});
LOGGER.info(resp3.join().toString());
client.close();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 -> completedFuture(
CoapResponse.ok("</sensors/temperature>", MediaTypes.CT_APPLICATION_LINK__FORMAT)
))
.post("/actuators/switch", req -> {
// ...
return completedFuture(CoapResponse.of(Code.C204_CHANGED));
})
// observable resource
.get("/sensors/temperature", req -> {
CoapResponse resp = CoapResponse.ok("21C").nextSupplier(() -> {
// we need to define a promise for next value
CompletableFuture<CoapResponse> promise = new CompletableFuture();
// ... complete once resource value changes
return promise;
}
);
return completedFuture(resp);
})
)
.build();
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 example client demonstrates how to build coap client.
- JDK 8
- gradle
./gradlew buildbuild./gradlew publishToMavenLocalpublish to local maven./gradlew dependencyUpdatesdetermine which dependencies have updates./gradlew useLatestVersionsupdate dependencies to the latest available versions
All 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