ObservableResource

abstract class ObservableResource(name: String) : CoapResource(source)

A resource clients can observe (RFC 7641). A GET or FETCH with Observe 0 that the handler answers with 2.xx adds the client to the observers; call notifyObservers whenever the state changes, and every observer gets a notification produced by calling the handler again with its registration request.

class Clock : ObservableResource("time") {
override suspend fun handleGet(context: RequestContext) =
CoapResponse.content(now()).withOptions { maxAge(1) }
}
// every second: clock.notifyObservers()

The server takes care of the rest of RFC 7641 §4: sequence numbers (§4.4), at most NSTART outstanding notifications per client, sending only the latest state when changes outpace the network and superseding an unacknowledged notification (§4.5.2), a Confirmable notification at least every CoapServerConfig.confirmableNotificationInterval (§4.5), removing observers on RST, timeout or a non-2.xx notification (§3.2, §4.5), and 4.04 notifications when the resource is removed. Over a reliable transport (RFC 8323 §7) the notifications go on the registration's connection, in order, and a closed connection removes its observers.

Constructors

Link copied to clipboard
constructor(name: String)

Properties

Link copied to clipboard
open val access: AccessPolicy?

Who may use this resource and, unless a child has a policy of its own, everything below it (ADR 0008). Null inherits the parent's, and the root's falls back to CoapServerConfig.defaultAccess; see AccessPolicy for when the server asks it.

Link copied to clipboard

Link attributes for /.well-known/core.

Link copied to clipboard

The child resources, in the order they were added.

Link copied to clipboard

Whether /.well-known/core lists this resource (RFC 6690 §4: which links to include is up to the server).

Link copied to clipboard
open override val isObservable: Boolean

Whether GET or FETCH with Observe registers observers (RFC 7641 §4.1); see ObservableResource.

Link copied to clipboard

the Uri-Path segment of this resource; the root has the empty name.

Link copied to clipboard

Whether notifications go Confirmable or Non-confirmable (RFC 7641 §4.5): a hint for datagram transports only, since a reliable transport has no message types and ignores it (RFC 8323 §7.2). Non-confirmable ones are cheaper for frequent changes; the server still sends a Confirmable one periodically, and to a client that neither message nor channel security authenticated at least every ninth notification, whose ACK shows the client still wants them (RFC 7641 §7). Only CoapMessageType.NON asks for Non-confirmable notifications; any other value asks for Confirmable ones.

Link copied to clipboard

How many clients observe this resource now.

Link copied to clipboard

The parent resource, or null for a root or a detached resource.

Link copied to clipboard

"/a/b", or "/" for the root.

Link copied to clipboard

Critical options this resource processes itself, beyond those the server implements (RFC 7252 §5.4.1). A request with any other unrecognized critical option gets 4.02 Bad Option before a handler runs. For example, a resource that honours conditional requests adds If-Match and If-None-Match (see RequestContext.preconditionsHold).

Functions

Link copied to clipboard

Adds child under this resource and returns it.

Link copied to clipboard

The child called name, or null.

Link copied to clipboard
fun find(segments: List<String>): CoapResource?

The resource at segments below this one, or null.

Link copied to clipboard
open suspend fun handle(context: RequestContext): CoapResponse

Dispatches to the handler for the request method (template method). Override it to handle methods generically, for example to proxy.

Link copied to clipboard
open suspend fun handleDelete(context: RequestContext): CoapResponse

DELETE (RFC 7252 §5.8.4).

Link copied to clipboard
open suspend fun handleFetch(context: RequestContext): CoapResponse

FETCH (RFC 8132 §2); observable like GET (RFC 8132 §2.4).

Link copied to clipboard
open suspend fun handleGet(context: RequestContext): CoapResponse

GET (RFC 7252 §5.8.1); also produces every Observe notification of an observable resource.

Link copied to clipboard
open suspend fun handleIPatch(context: RequestContext): CoapResponse

iPATCH (RFC 8132 §3).

Link copied to clipboard
open suspend fun handlePatch(context: RequestContext): CoapResponse

PATCH (RFC 8132 §3).

Link copied to clipboard
open suspend fun handlePost(context: RequestContext): CoapResponse

POST (RFC 7252 §5.8.2).

Link copied to clipboard
open suspend fun handlePut(context: RequestContext): CoapResponse

PUT (RFC 7252 §5.8.3).

Link copied to clipboard

Tells the observers that the state changed. Returns at once; notifications are sent in the background.

Link copied to clipboard

Removes and returns the child called name. Its observers, and those of its children, get a 4.04 notification and are removed (RFC 7641 §3.2).

Link copied to clipboard
open override fun toString(): String