From 14ef86e37a0c90790e3e152157710b69b69996d3 Mon Sep 17 00:00:00 2001 From: Zihan Dai <99155080+PDGGK@users.noreply.github.com> Date: Tue, 11 Aug 2026 00:02:12 +1000 Subject: [PATCH] Document how to verify the ThingsBoard compile-only surface The iotdb-thingsboard-table module implements ThingsBoard storage SPIs but cannot depend on ThingsBoard at build time: neither org.thingsboard.common:data nor org.thingsboard:dao is published to Maven Central. src/provided/java therefore carries a compile-only surface of the types the module touches, excluded from the built jar so the real classpath supplies them at runtime. That keeps the module buildable for everyone, at the cost that the surface can drift from the real interfaces with nothing in the default build noticing. This adds the procedure for checking that it has not: build the two ThingsBoard modules locally, swap the compile-only surface for the real artifacts, and run the suite. The procedure is deliberately not wired into the default build, since that would require every contributor and every CI run to clone and build ThingsBoard first. Includes a control for confirming the surface was actually removed -- a green build proves nothing if the compile-only sources are still on the source path -- and records the result against ThingsBoard 4.3.1.2: 190 unit tests and 57 container integration tests green, no drift. Signed-off-by: Zihan Dai <99155080+PDGGK@users.noreply.github.com> --- .../VERIFYING-AGAINST-THINGSBOARD.md | 171 ++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 iotdb-thingsboard-table/VERIFYING-AGAINST-THINGSBOARD.md diff --git a/iotdb-thingsboard-table/VERIFYING-AGAINST-THINGSBOARD.md b/iotdb-thingsboard-table/VERIFYING-AGAINST-THINGSBOARD.md new file mode 100644 index 0000000..850e496 --- /dev/null +++ b/iotdb-thingsboard-table/VERIFYING-AGAINST-THINGSBOARD.md @@ -0,0 +1,171 @@ + + +# Verifying the compile-only ThingsBoard surface + +This module implements ThingsBoard storage SPIs (`TimeseriesDao`, +`TimeseriesLatestDao`, `AttributesDao`) but does **not** depend on ThingsBoard at +build time. ThingsBoard's `dao` and `common/data` artifacts are not published to +Maven Central: + +``` +g:org.thingsboard.common AND a:data -> numFound 0 +g:org.thingsboard AND a:dao -> numFound 0 +``` + +so `src/provided/java` carries a compile-only surface of the ThingsBoard types +this module touches. Those sources are visible to `javac` only and are excluded +from the built jar (see the `maven-jar-plugin` `org/thingsboard/**` exclude), so +the real ThingsBoard classpath supplies the genuine types at runtime. + +That arrangement keeps the module buildable for everyone, but it has one cost: a +hand-written surface can drift from the real interfaces, and nothing in the +default build would notice. **This document is how you check that it has not.** + +The procedure below is deliberately *not* wired into the default build. Doing so +would require every contributor and every CI run to clone and build ThingsBoard +first, which is the situation the compile-only surface exists to avoid. + +## What it verifies + +Removing the compile-only surface and putting the real ThingsBoard artifacts on +the classpath means `javac` type-checks this module against the genuine types, +and the tests then exercise the DAO logic through them. + +| Layer | Covered | +|---|---| +| the surface binds | every stub type and all three `implements` clauses | +| behaviour under mocks | unit tests | +| behaviour against a real server | container integration tests, real IoTDB | + +## Procedure + +Requires JDK 17, Maven, Docker (for the integration tests) and roughly 250 MB of +disk: the shallow clone below is about 140 MB and grows to about 240 MB once the +two modules are built. The installed artifacts add about 10 MB to your local +Maven repository. + +**1. Build the ThingsBoard artifacts locally.** Use the version this module +targets; it is declared as `thingsboard.version` in `pom.xml`. + +```bash +git clone --depth 1 --branch v4.3.1.2 https://github.com/thingsboard/thingsboard.git +cd thingsboard +mvn install -pl common/data,dao -am -DskipTests +``` + +This installs `org.thingsboard.common:data` and `org.thingsboard:dao` (plus the +modules they need) into your local repository. It does not require a full +ThingsBoard build. + +**2. Point the module at them.** Apply this change locally — **do not commit +it**, because the artifacts are not resolvable from any configured repository and +committing it would break every build that has not run step 1. + +In `iotdb-thingsboard-table/pom.xml`: + +* remove the `src/provided/java` entry from ``, leaving only + `src/main/java` +* add, at `provided` scope: + +```xml + + org.thingsboard.common + data + 4.3.1.2 + provided + + + org.thingsboard + dao + 4.3.1.2 + provided + + + org.apache.commons + commons-lang3 + 3.18.0 + provided + +``` + +`commons-lang3` must match the version ThingsBoard itself pins (`3.18.0` for +4.3.1.2; see `commons-lang3.version` in ThingsBoard's root `pom.xml`). The real +`EntityType` uses `org.apache.commons.lang3.Strings`, which does not exist before +3.18.0 — with an older version every test in a suite that touches `EntityType` +fails at static initialisation with `NoClassDefFoundError`, which looks like a +drift failure and is not one. + +**3. Build and test.** + +```bash +mvn -P with-thingsboard -pl iotdb-thingsboard-table test # unit +mvn -P with-thingsboard -P iotdb-table-it -pl iotdb-thingsboard-table verify # + container ITs +``` + +`verify` also runs `apache-rat`, so if you add any file while working through +this it needs the standard licence header or the build fails after the tests +have already passed. + +## Confirming the surface was actually removed + +A green build proves nothing on its own: if the compile-only sources are still on +the source path, everything compiles exactly as before. Check the compiler line. + +``` +with the compile-only surface: Compiling 58 source files +with the real artifacts: Compiling 19 source files +``` + +The difference is the size of the compile-only surface. If you still see the +larger number, the `` edit did not take effect and the run +tells you nothing about the real types. + +`mvn -P with-thingsboard -pl iotdb-thingsboard-table dependency:list | grep thingsboard` +should also list the real artifacts at `provided` scope. + +## Result on 2026-08-10, against ThingsBoard 4.3.1.2 + +``` +Compiling 19 source files (58 with the compile-only surface) +Tests run: 190, Failures: 0, Errors: 0 unit +Tests run: 57, Failures: 0, Errors: 0 container ITs, real IoTDB +BUILD SUCCESS +``` + +Integration tests by suite: `IoTDBTableLatestDaoIT` 19, +`IoTDBTableTimeseriesAggregationIT` 13, `IoTDBTableAttributesDaoIT` 12, +`IoTDBTableTimeseriesDaoIT` 10, `IoTDBTableTtlIT` 2, +`IoTDBTableIngestionBenchmarkIT` 1. + +No drift: every type in the compile-only surface matched, and all three +`implements` clauses bound against the real interfaces. + +This has not been run inside a live ThingsBoard instance. It establishes that the +types bind and that the DAO behaves correctly against a real IoTDB while using +them; it does not establish that ThingsBoard as a whole runs on this DAO. + +## When ThingsBoard publishes its artifacts + +If `org.thingsboard.common:data` and `org.thingsboard:dao` become resolvable from +a configured repository, the compile-only surface can be deleted and step 2 can +become the permanent configuration. Until then, this procedure is the way to +check it.