From 5fe0b372ac180f083d91c8dfa01b12cc73e21724 Mon Sep 17 00:00:00 2001 From: Matthias Kurz Date: Thu, 8 Oct 2026 12:11:02 +0200 Subject: [PATCH] Fix outdated docs code samples and run the docs tests in CI The ServerConfigStartup and transaction samples still used Ebean APIs that have been removed in the meantime (ServerConfig and the Ebean class), so they did not compile anymore. That went unnoticed, because CI only validated the docs, but never compiled or ran the samples. Their models did not even get enhanced, as the docs build did not enhance its test sources. Also point out that a ServerConfigStartup has to be covered by an "ebean." config line, since Ebean does not scan the classpath for it when used with Play Ebean. --- .github/workflows/build-test.yml | 2 +- docs/build.sbt | 3 ++- .../working/javaGuide/main/sql/JavaEbean.md | 6 ++++-- .../code/javaguide/ebean/JavaEbeanTest.java | 18 ++++++++++-------- .../javaguide/ebean/MyServerConfigStartup.java | 7 ++++--- 5 files changed, 21 insertions(+), 15 deletions(-) diff --git a/.github/workflows/build-test.yml b/.github/workflows/build-test.yml index 6a65080d..f3242d63 100644 --- a/.github/workflows/build-test.yml +++ b/.github/workflows/build-test.yml @@ -29,7 +29,7 @@ jobs: with: java: 17, 11 scala: 2.13.x, 3.x - cmd: cd docs && sbt ++$MATRIX_SCALA validateCode + cmd: cd docs && sbt ++$MATRIX_SCALA "validateCode; test" tests: name: Tests diff --git a/docs/build.sbt b/docs/build.sbt index 5ca24f8a..ccf9eab4 100644 --- a/docs/build.sbt +++ b/docs/build.sbt @@ -46,8 +46,9 @@ lazy val docs = project ) .settings(PlayEbean.unscopedSettings: _*) .settings( + // The code samples are test sources, so enhance their models there inConfig(Test)( - Seq( + PlayEbean.scopedSettings ++ Seq( playEbeanModels := Seq("javaguide.ebean.*") ) ): _* diff --git a/docs/manual/working/javaGuide/main/sql/JavaEbean.md b/docs/manual/working/javaGuide/main/sql/JavaEbean.md index 8ecb2284..96da08e4 100644 --- a/docs/manual/working/javaGuide/main/sql/JavaEbean.md +++ b/docs/manual/working/javaGuide/main/sql/JavaEbean.md @@ -37,12 +37,14 @@ In this example, we have access to two Ebean servers - each using its own databa Each `ebean.` config line (as above) can map *any* classes that Ebean may be interested in registering (eg. `@Entity`/`Model` classes, `@Embeddable`s, custom `ScalarType`s and `CompoundType`s, `BeanPersistController`s, `BeanPersistListener`s, `BeanFinder`s, `ServerConfigStartup`s, etc). These can be individually listed separated by commas, and/or you can use the wildcard `.*`. For example, `models.*` registers with Ebean all classes within the models package that Ebean can make use of. -To customise the underlying Ebean Server configuration, you can either add a [`conf/application.yaml`](https://ebean.io/docs/intro/configuration/) file, or create an instance of the `ServerConfigStartup` interface to programmatically manipulate the Ebean `ServerConfig` before the server is initialised. +To customise the underlying Ebean Server configuration, you can either add a [`conf/application.yaml`](https://ebean.io/docs/intro/configuration/) file, or implement the `ServerConfigStartup` interface to programmatically manipulate the Ebean `DatabaseBuilder` before the server is initialised. As an example, the fairly common problem of reducing the sequence batch size in order to minimise sequence gaps, could be solved quite simply with a class like this: @[content](code/javaguide/ebean/MyServerConfigStartup.java) +Make sure that such a class is covered by an `ebean.` config line, for example by putting it into the `models` package. Play Ebean registers the configured classes with Ebean explicitly, which disables Ebean's own classpath scanning, so Ebean silently ignores any `ServerConfigStartup` that is not covered. + Note that Ebean will also make use of a `conf/orm.xml` file (if present), to configure ``. #### Using a read replica @@ -108,7 +110,7 @@ By default Ebean will use transactions. However these transactions will be creat @[transaction](code/javaguide/ebean/JavaEbeanTest.java) -So, if you want to do more than one action in the same transaction you can use TxRunnable and TxCallable: +So, if you want to do more than one action in the same transaction you can use `DB.execute` (or `DB.executeCall` to return a value): @[txrunnable](code/javaguide/ebean/JavaEbeanTest.java) diff --git a/docs/manual/working/javaGuide/main/sql/code/javaguide/ebean/JavaEbeanTest.java b/docs/manual/working/javaGuide/main/sql/code/javaguide/ebean/JavaEbeanTest.java index 2ac60307..5aa31174 100644 --- a/docs/manual/working/javaGuide/main/sql/code/javaguide/ebean/JavaEbeanTest.java +++ b/docs/manual/working/javaGuide/main/sql/code/javaguide/ebean/JavaEbeanTest.java @@ -8,7 +8,8 @@ import static org.junit.Assert.*; import static play.test.Helpers.*; -import io.ebean.Ebean; +import io.ebean.DB; +import io.ebean.Transaction; import java.util.HashMap; import java.util.List; import java.util.Map; @@ -91,11 +92,11 @@ public void txRunnable() { // ###insert: ... - Ebean.execute( + DB.execute( () -> { // code running in "REQUIRED" transactional scope // ... as "REQUIRED" is the default TxType - System.out.println(Ebean.currentTransaction()); + System.out.println(DB.currentTransaction()); Task task = Task.find.byId(34L); task.setDone(true); @@ -131,16 +132,17 @@ public void traditional() { createTask(); // #traditional - Ebean.beginTransaction(); - try { + // ###insert: import io.ebean.*; + + // ###insert: ... + + try (Transaction transaction = DB.beginTransaction()) { Task task = Task.find.byId(34L); task.setDone(true); task.save(); - Ebean.commitTransaction(); - } finally { - Ebean.endTransaction(); + transaction.commit(); } // #traditional diff --git a/docs/manual/working/javaGuide/main/sql/code/javaguide/ebean/MyServerConfigStartup.java b/docs/manual/working/javaGuide/main/sql/code/javaguide/ebean/MyServerConfigStartup.java index 6c82a80c..4933165f 100644 --- a/docs/manual/working/javaGuide/main/sql/code/javaguide/ebean/MyServerConfigStartup.java +++ b/docs/manual/working/javaGuide/main/sql/code/javaguide/ebean/MyServerConfigStartup.java @@ -6,12 +6,13 @@ // ###replace: package models; package javaguide.ebean; -import io.ebean.config.ServerConfig; +import io.ebean.DatabaseBuilder; import io.ebean.event.ServerConfigStartup; public class MyServerConfigStartup implements ServerConfigStartup { - public void onStart(ServerConfig serverConfig) { - serverConfig.setDatabaseSequenceBatchSize(1); + @Override + public void onStart(DatabaseBuilder config) { + config.databaseSequenceBatchSize(1); } } // #content