Californium is the Java implementation of CoAP for IoT cloud services

CoAP on the cloud side of an IoT deployment

Eclipse Californium is a Java implementation of RFC 7252, the Constrained Application Protocol, for IoT cloud services. The README states the design intent precisely: the focus is on scalability and usability instead of the resource-efficiency that matters for embedded devices, and yet the library is also suitable for embedded JVMs.

That framing explains a lot about the project. CoAP is the protocol a device uses to talk to a service over UDP with a compact binary format and a handful of REST-like methods, and the two ends of that conversation have opposite constraints. A sensor has a few kilobytes of RAM, a server has thousands of concurrent endpoints. Californium is written for the second case.

The homepage is eclipse.org/californium, and the site coap.technology carries further information. The primary language is Java, the topics are coap, dtls and internet-of-things, and the licence is a custom one that GitHub cannot classify, with the details in the LICENSE file and a NOTICE file beside it. Any specific question about those terms belongs with your own counsel.

The repository also carries a SECURITY.md, a CODE_OF_CONDUCT.md and a CONTRIBUTING.md, and the last push was on 2026-10-08, so the project is being worked on.

One core module with satellites around it

The top level of the repository is a multi-module Maven project, and the module names describe the ecosystem rather than a single library.

californium-core is the implementation itself. Around it sit cf-utils for shared utilities, cf-oscore for object security, the OSCORE-based authorisation layer, and cf-pubsub for publish and subscribe. californium-proxy2 is a proxy, and scandium-core is the other half of the DTLS side, since Scandium is Californium's DTLS library.

Then there are the connectors. element-connector and element-connector-tcp-netty are the transports, with the Netty variant handling TCP for CoAP over reliable transports. californium-osgi packages the stack as an OSGi bundle, and californium-tests and demo-apps carry the test suites and the runnable examples.

The packaging is a little unusual for a Java library, and the reason is deployment rather than API. Californium has to run in environments as different as a plain JVM server and an OSGi container, and the assembly directory, the bom directory for the dependency list and the legal directory for licence headers are all there to support that.

The presence of MIGRATION_HINTS.md and MIGRATION_HINTS_4.md at the root is worth noticing, because it tells you that crossing the 3.x to 4.x boundary is a documented migration rather than a drop in change.

Adding californium-core to a Maven project

The artifacts are published to Maven Central for both milestones and releases, and the README gives the dependency block with the version you choose.

For the current release line it is:

  <dependencies>
    ...
    <dependency>
            <groupId>org.eclipse.californium</groupId>
            <artifactId>californium-core</artifactId>
            <version>3.14.0</version>
    </dependency>
    ...
  </dependencies>
  ...

and for the milestone line the same block with the version set to 4.0.0-M6. The README attaches an important note to the milestone: the API of 4.0.0-M6 is not stable yet. That is the line to read twice before choosing, because the difference between a patch upgrade and a major API change is the difference between an afternoon and a migration project.

If you want the newest build from main, the artifacts are not on Maven Central but in Californium's own Eclipse project repository, so you have to add the repository to your pom first:

  <repositories>
    ...
    <repository>
      <id>repo.eclipse.org</id>
      <name>Californium Repository</name>
      <url>https://repo.eclipse.org/content/repositories/californium/</url>
    </repository>
    ...
  </repositories>

After that you can depend on 4.0.0-SNAPSHOT. The README calls this a bold move, which is a fair description of a snapshot dependency in a production pom.

Building the source across four JDK versions

Building Californium needs a working Maven installation, and then a single command from the project root:

$ mvn clean install

Executable JARs of the examples with all dependencies bundled end up in the demo-apps/run folder, which is the quickest way to see the protocol working without wiring up a project.

The build process in the main branch is tested for jdk8, jdk 11, jdk 17 and jdk 21, so the compatibility window is wide. Javadoc generation is opt-in through a property rather than a separate goal, and the README gives two variants:

$ mvn clean install -DcreateJavadoc=true

$ mvn clean install -DuseToolchainJavadoc=true

The second uses the JDK toolchain's own javadoc, which is what you want when the Javadoc tool on your PATH is from a different JDK than the one compiling the code.

There is also an EdDSA build variant, and the README is direct about its requirement: supporting EdDSA requires Java 17 or newer. Earlier versions of Californium supported the ed25519-java library at runtime, but the README says that library seems to be unmaintained and the support has therefore been removed. So a project that needs EdDSA now has a hard floor of Java 17, whatever it used to target.

Bouncy Castle, and a SecureRandom that can block for a minute

The most interesting operational detail in the README is about Bouncy Castle, and it is worth reading closely because the problem it describes is subtle.

Experimental support for using Bouncy Castle as an alternative JCE provider exists since version 3.0, with bcprov-jdk15on, bcpkix-jdk15on and bctls-jdk15on from version 1.69. Version 4.0 supports BC version 1.78.1. The unit tests can be run with the bc-tests profile:

$ mvn clean install -Pbc-tests

The README then explains the catch in unusually blunt terms. Running the unit tests with Bouncy Castle uncovers differences that required the implementation to be adapted, and it is assumed that more will be found and more adaptation required. And Californium will not be able to support Bouncy Castle questions, with or without a relation to Californium, so issues may be filed but may not be answerable.

The specific problem is the SecureRandom generator in BC, which is based on SecureRandom.getInstanceStrong(). That has blocking behaviour by default, and if the platform does not have enough entropy to start it, BC waits until entropy becomes available, which in common cases starts quickly and in some cases takes up to 60 seconds or more. On a Linux variant, rng-tools may help provide that entropy. The other option is to set CALIFORNIUM_JCE_PROVIDER to BC_NON_BLOCKING_RANDOM instead of BC, which adapts SecureRandom to a possibly weaker non-blocking implementation, and that may not work on every platform, Android in particular, where the alternative is to set the securerandom.strongAlgorithms security property to a suitable Android algorithm.

This is a real deployment consideration for anyone running Californium on constrained entropy environments, and the README's advice is to test the combination you need yourself.

A public interop server to test a client against

There is a test server running at coap://californium.eclipseprojects.io:5683/, and it is an instance of the cf-plugtest-server from the demo apps. The root resource responds with its current version, which is a cheap way to confirm that your client's DTLS handshake and request path work at all.

The server is intended for testing the interoperability of CoAP and DTLS 1.2, and the data it returns is representative of a working deployment rather than a toy.

For a preview of the Return Routability Check for DTLS 1.2 and DTLS 1.3, the README points at a separate feature/rrc branch with a link to the relevant TLS working group draft. That is a good example of how the project handles experimental protocol work, by keeping it off the main branch and available for people who want to try it.

The demo-apps directory, with its plugtest server and the runnable JARs, means you can also run the same server locally, which is what you want when testing against something that is not on the public internet.

Editorial conclusion

Californium suits a Java team building the server side of a CoAP deployment, where the constraint is many concurrent endpoints rather than kilobytes of RAM, since the project is built for scale and ships the OSGi, proxy, pub-sub and test modules alongside the core. It is the wrong choice for the device itself if you are targeting a microcontroller, and you should not depend on the 4.0 milestone line for production yet, because the README says the API of 4.0.0-M6 is not stable. Before adding the dependency, decide between the 3.14.0 release line and the 4.0 milestones, and read the MIGRATION_HINTS files in the repository root for the differences.

Frequently asked questions

Official sources

1. eclipse-californium/californium on GitHub
2. Issues
3. Project website
4. README
5. Releases