[8.x] Fix outdated docs code samples and run the docs tests in CI

.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

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.*")
       )
     ): _*

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 `<entity-mappings>`.
 
 #### 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)
 

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
 

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