Documentation

Resource Management (Edge Android SDK 3.0 and later)

The Nabto Edge Android SDK wraps the underlying native Nabto Edge Client SDK. To handle release of Nabto Edge resources in a predictable and efficient manner, the AutoCloseable interface is implemented by classes that wrap native resources (requires Nabto Edge Android SDK 3.0 or later). In this way, the application is in control of the life cycle of objects meaning that for instance connection resources can be released immediately when not needed any more instead of waiting for the runtime’s garbage collector to release the resources.

To benefit from AutoCloseable, allocate resources using the try-with-resources construct:

try (Connection connection = client.createConnection()) {
    connection.updateOptions(options.toString());
    connection.connect();
    // use the connection
    // ...
    connection.closeConnection();
} catch (Exception e) {
    // ...
}

When execution reaches the end of the try { ... } block, the coap object’s close() function is automatically invoked and the native Nabto resources are released.

If for some reason it is not feasible with a try-with-resources construct, the close() function can be invoked directly by the application. For instance, in a connection cache, your cache implementation can provide a stop() function that explicitly invokes close() on all connection objects in the cache.

Note that the Nabto Edge Android SDK classes that implement AutoCloseable, all override close() in the interface to not throw any exceptions (the default close() does): The underlying native Nabto Client SDK functions for resource cleanup do not fail.

To benefit from AutoCloseable in Kotlin, you invoke the use function on objects that implement AutoCloseable:

NabtoClient.create(context).use { client ->
    createStreamConnection(client)?.use { connection ->
        connection.awaitConnect()
        // use the connection
        // ...
        connection.awaitConnectionClose()
    }
}

When the end of the closure passed to use is reached, close() is automatically invoked.

Breaking Change from 2.4.2 to 3.0.0

A breaking change was necessary to introduce AutoCloseable support: With the Nabto Edge Android SDK up until version 2.4.2, the API provided close() methods with different semantics than what is required by AutoCloseable’s close(): The 2.x version’s close() was typically a “soft” close. For instance for Stream instances, it meant gracefully closing the write direction by sending a reset to the other peer which in turn would then see an EOF on the stream.

With version 3 of the Nabto Edge Android SDK, the close() semantics is now cleaning up of low level resources with no high level “niceness” like resetting a stream. This means that the high level “soft” close has been moved to (e.g.) streamClose() that must still be invoked by the application.

Summary: Applications that earlier invoked Connection.close(), Stream.close() or TcpTunnel.close() must be changed to use Connection.connectionClose(), Stream.streamClose() or TcpTunnel.tunnelClose(), respectively, when upgrading to Nabto Edge Android SDK 3.0. This is regardless of using the AutoCloseable features or not.