October, 2024
The version 3.x is now out for about more than three years and reached version 3.13.0. I have started to work on a 4.0 on October 2024 starting with removing deprecates APIs.
To migrate to the 4.0 this gives some hints to do so. If you miss something, don't hesitate to create an issue.
Please, keep in mind, that the 4.0 API is under develop.
This document doesn't contain hints for migrating versions before 3.0. That excludes also hints to migrate any of the 3.0 MILESTONE releases.
If a 3.0.0 or newer is used, it's recommended to update first to 3.13.0 and cleanup all deprecation using the documentation on the deprecation.
Some of the configuration properties are not longer supported (they have been marked as deprecated) and it is recommended to generate new property files and compare the content with the ones previous in use.
The plan is still to be able to use Californium with java 8. That requires also to use Android 8, API level 26. According a discussion, it is possible to desugaring java 8 back to Android versions before
For a local build new Java versions will be required. For now I would consider to support java 17 as minimum version to build Californium.
Californium 3 used in several functions two ScheduledExecutorService for execution. The main was intended to be used only for very short and fast tasks in a "non-blocking" way. The "scheduled" tasks of that main executor are mainly intended to switch then to {@link SerialExecutor} to serialize executing jobs in the scope of an (CoAP) Exchange (DTLS) Conection secondary executor is the intended for longer running tasks, e.g. cleanup jobs. This long jobs must not execute too frequently and may be delayed. To optimize the performance the main executor should be created with ExecutorsUtil.newScheduledThreadPool(int, ThreadFactory) and the secondary with ExecutorsUtil.newDefaultSecondaryScheduler(String).
In order to simplify the API for Californium 4, this behavior is mapped into the ProtocolScheduledExecutorService interface. This replaces the two executors in several functions. It may be provided with a custom implementation or by ExecutorsUtil.newProtocolScheduledThreadPool(int, ThreadFactory) and
ExecutorsUtil.newSingleThreadedProtocolExecutor(ThreadFactory).
Supports virtual threads for UDP receivers and senders, if the JVM supports it. Otherwise platform daemon threads are used. Chosen by -1 as number of threads in UDP.RECEIVER_THREAD_COUNT and UDP.SENDER_THREAD_COUNT.
Additional to the deprecated marked API, the implementation of the features are also removed.
The functions to reduce the HelloVerifyRequests for specific cases, PSK (DTLS_USE_HELLO_VERIFY_REQUEST_FOR_PSK) and resumption handshakes (DTLS_VERIFY_PEERS_ON_RESUMPTION_THRESHOLD)have been removed. The general function (DTLS_USE_HELLO_VERIFY_REQUEST) to disable it is still available. The unit-test have been updated according this changed behavior.
The functions to handle the "deprecated CID" definition in the drafts before the RFC9146 have been removed. If still used in some other implementations, please update those other implementations to the final RFC.
With this major version the DTLS 1.2 Connection ID is enabled by default with a length of 6 bytes. Therefore using the default by using an <empty> value will not longer work to disable this feature. Please use -1, if you want to disable it.
The removing of the deprecated function DTLSConnector.onInitializeHandshaker showed, that a single custom SessionListener is not enough, if a derived class has overridden it. Therefore DTLSConnector.addSessionListener has been added.
In some cases SHA384 was misspelled as SHA378. That's fixed but causes also to fail reading old Californium3.properties.
Supports virtual threads for DTLS receivers, if the JVM supports it. Otherwise platform daemon threads are used. Chosen by -1 as number of threads in DTLS.RECEIVER_THREAD_COUNT.
The Option is changed to be immutable, remove the setters.
The apache http libraries haven been update to http-client 5.4 and http-core 5.3. The previous version used a pre-processing filter to implement a generic proxy (catch all), which added the path "proxy" to the incoming request. With this update the RequestRouter is used and so the routing may have changed slightly according the details. The proxy handler is now called with the original path without additional "proxy".
The http-client 5.4 follows RFC 7540, 8.1.2.3, Request Pseudo-Header Fields and deprecates the use of a "userinfo" field. Such request will fail.
Removed StringUtil.toHostString() (support Java 6). Java 8 is the minimum supported version for runtime, therefore use InetSocketAddress.getHostString() directly.
Removed org.eclipse.californium.elements.util.StandardCharsets, obsoleted by java 8 java.nio.charset.StandardCharsets.
Removed org.eclipse.californium.elements.util.Filter, obsoleted by java 8 java.util.function.Predicate.
Removed org.eclipse.californium.elements.util.Base64, obsoleted by java 8 java.util.Base64.
org.eclipse.californium.elements.util.StringUtil.base64ToByteArray(String) throws now IllegalArgumentException for invalid content instead of returning an empty array.
Introduce ProtocolScheduledExecutorService interface to simplify main and secondary executors.
Add ExecutorsUtil.newProtocolScheduledThreadPool(int, ThreadFactory) and
ExecutorsUtil.newSingleThreadedProtocolExecutor(ThreadFactory) to created implementations of ProtocolScheduledExecutorService.
The removing of the deprecated function DTLSConnector.onInitializeHandshaker showed, that a single custom SessionListener is not enough, if a derived class has overridden it. Therefore DTLSConnector.addSessionListener has been added.
Removing the HelloVerifyRequests for specific cases obsoletes also ResumptionVerifier.skipRequestHelloVerify and ExtendedResumptionVerifier. Also the last parameter of DtlsHealth.dump is removed.
The functions of the obsolete and removed DtlsHealthExtended and DtlsHealthExtended2 are moved into
DtlsHealth.
The functions of the obsolete and removed DatagramFilterExtended are moved into
DatagramFilter.
Change scope of DTLSFlight.wrapMessage to private.
The names CipherSuite.TLS_ECDHE_PSK_WITH_AES_256_GCM_SHA378, and CipherSuite.TLS_PSK_WITH_AES_256_GCM_SHA378 are corrected into CipherSuite.TLS_ECDHE_PSK_WITH_AES_256_GCM_SHA384, and CipherSuite.TLS_PSK_WITH_AES_256_GCM_SHA384.
Merged ReadWriteLockConnectionStore into ResumptionSupportingConnectionStore and remove obsolete ReadWriteLockConnectionStore.
Uses the new introduced ProtocolScheduledExecutorService.
The functions of the obsolete and removed ExtendedCoapStack are moved into
CoapStack.
Rename ExtendedCoapStackFactory into CoapStackFactory.
Remove setters from Option.
Introduce OptionNumber to compare Option and OptionDefintion based on their number.
Remove CropRotation. Please use an other available deduplication algorithms.
Remove ResponseConsumer. Replaced by Consumer<Response>.
Endpoint, CoapServer, CoapClient, CoapStack, and Layer replaces the main and secondary executor by the new introduced ProtocolScheduledExecutorService. Also replaces void setExecutors(ScheduledExecutorService mainExecutor, ScheduledExecutorService secondaryExecutor) by void setExecutor(ProtocolScheduledExecutorService executor).
Add Endpoint.getExecutor().
ClientObserveRelation and CoapObserveRelation switched to use the Endpoint executor instead of a separate argument.
Rename HttpServer.registerVirtual into register.