Refactor from Jackson Core to avaje-json-core

docs/LIBRARY.md

@@ -183,6 +183,8 @@ database.save(customer);
 | Configure database and `Database` bean | [add-ebean-postgres-database-config.md](guides/add-ebean-postgres-database-config.md) |
 | Add PostgreSQL test container support | [add-ebean-postgres-test-container.md](guides/add-ebean-postgres-test-container.md) |
 | Generate DB migrations | [add-ebean-db-migration-generation.md](guides/add-ebean-db-migration-generation.md) |
+| Migrate JSON APIs from Jackson core to avaje-json-core | [migrating-json-jackson-core-to-avaje-json-core.md](guides/migrating-json-jackson-core-to-avaje-json-core.md) |
+| Know which `@DbJson` types need Jackson vs built-in | [dbjson-mapping-support.md](guides/dbjson-mapping-support.md) |
 | Model entity beans correctly | [entity-bean-creation.md](guides/entity-bean-creation.md) |
 | Use Lombok safely with entities | [lombok-with-ebean-entity-beans.md](guides/lombok-with-ebean-entity-beans.md) |
 | Write type-safe query bean queries | [writing-ebean-query-beans.md](guides/writing-ebean-query-beans.md) |

docs/guides/AGENTS.md

@@ -12,6 +12,7 @@ Key guides (fetch and follow when performing the relevant task):
 - Maven POM setup: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-maven-pom.md
 - Database configuration: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/add-ebean-postgres-database-config.md
 - Migrate to `Database.builder()`: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-to-database-builder.md
+- Migrate JSON APIs from Jackson core to avaje-json-core: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/migrating-json-jackson-core-to-avaje-json-core.md
 - Write queries with query beans: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/writing-ebean-query-beans.md
 - Persisting and transactions: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/persisting-and-transactions-with-ebean.md
 - Query metrics and naming: https://raw.githubusercontent.com/ebean-orm/ebean/HEAD/docs/guides/ebean-query-metrics.md

docs/guides/README.md

@@ -23,6 +23,7 @@ existing Maven project. Complete the steps in order.
 | Guide | Description |
 |-------|-------------|
 | [Migrate to `Database.builder()`](migrating-to-database-builder.md) | Replace legacy `new DatabaseConfig()` and `DatabaseFactory.create(...)` code with `Database.builder()` and `DatabaseBuilder.build()`. Includes common rewrites, fluent builder equivalents, and manual-review cases for semi-automated upgrades |
+| [Migrate JSON APIs from Jackson core to avaje-json-core](migrating-json-jackson-core-to-avaje-json-core.md) | Cut over `JsonParser`/`JsonGenerator`/`JsonFactory` usage to `JsonReader`/`JsonWriter`/`JsonStream`, including `DatabaseBuilder`/`DatabaseConfig` JSON config changes and validation checklist |
 
 ## Observability
 
@@ -38,6 +39,7 @@ existing Maven project. Complete the steps in order.
 |-------|-------------|
 | [Entity Bean Creation](entity-bean-creation.md) | How to generate clean, idiomatic Ebean entity beans for AI agents; patterns and anti-patterns; field visibility and accessor guidance; minimal boilerplate |
 | [Lombok with Ebean entity beans](lombok-with-ebean-entity-beans.md) | Which Lombok annotations to use and avoid on entity beans; why `@Data` is incompatible with Ebean; how to use `@Getter` + `@Setter` + `@Accessors(chain = true)` |
+| [`@DbJson` mapping support (built-in vs Jackson)](dbjson-mapping-support.md) | Which `@DbJson` / `@DbJsonB` property types are handled by the built-in avaje-json-core support versus which require `ebean-jackson-mapper` (Jackson `ObjectMapper`); supported `String`/`List`/`Set`/`Map` matrix; enum-key and `@DbArray` notes |
 
 ## Querying
 

docs/guides/dbjson-mapping-support.md

@@ -0,0 +1,116 @@
+# Guide: `@DbJson` / `@DbJsonB` mapping support — built-in vs Jackson ObjectMapper
+
+## Purpose
+
+Ebean can map `@DbJson` and `@DbJsonB` properties in two ways:
+
+- **Built-in** JSON support, backed by **avaje-json-core** — no extra dependency.
+- **Jackson `ObjectMapper`**, provided by the **`ebean-jackson-mapper`** module — used
+  for everything the built-in support does not handle.
+
+This guide lists exactly which property types are handled built-in and which require
+`ebean-jackson-mapper`.
+
+> If a property type is **not** handled built-in and `ebean-jackson-mapper` is not on the
+> classpath, Ebean fails fast at startup:
+>
+> ```text
+> Unsupported @DbJson mapping - Missing dependency ebean-jackson-mapper?
+> Jackson ObjectMapper not present for <property>
+> ```
+
+---
+
+## Quick reference
+
+| Property type | Built-in (avaje-json-core) | Needs `ebean-jackson-mapper` |
+|---|:---:|:---:|
+| `String` | ✅ | |
+| `List<String>`, `List<Long>` | ✅ | |
+| `Set<String>`, `Set<Long>` | ✅ | |
+| `Map<String, Object>`, `Map<String, ?>` | ✅ | |
+| `Map<String, String>` | ✅ | |
+| `Map<Enum, Object>`, `Map<Enum, String>` | ✅ | |
+| `List`/`Set` of any other element type (`Integer`, `Double`, `UUID`, `LocalDate`, an enum, a POJO, …) | | ✅ |
+| `Map` with a typed value other than `String`/`Object` (`Map<String,Integer>`, `Map<String,UUID>`, …) | | ✅ |
+| `Map` with a key other than `String` or an enum (`Map<Integer, …>`, `Map<UUID, …>`) | | ✅ |
+| POJOs, records, or any other type | | ✅ |
+
+---
+
+## Built-in support (no Jackson required)
+
+The built-in path materialises JSON into the *natural* JSON value types
+(`String`, `Long`, `BigDecimal`, `Boolean`, `Map`, `List`). It is therefore type-safe only
+for the following declared property types:
+
+- **`String`** — stored as raw JSON text.
+- **`List<String>`** and **`List<Long>`**.
+- **`Set<String>`** and **`Set<Long>`**.
+- **`Map<K, V>`** where:
+  - the key `K` is `String` or an **enum**, and
+  - the value `V` is `Object`, `String`, or a wildcard `?`.
+
+  So `Map<String,Object>`, `Map<String,String>`, `Map<Enum,Object>` and `Map<Enum,String>`
+  are all built-in.
+
+These mappings work across all supported storage types — `VARCHAR`, `CLOB`, `BLOB`, and
+Postgres `json` / `jsonb` — without `ebean-jackson-mapper`.
+
+---
+
+## Everything else → Jackson `ObjectMapper`
+
+Any other `@DbJson` / `@DbJsonB` property routes to the Jackson `ObjectMapper` path, which
+requires `ebean-jackson-mapper`:
+
+- **Typed collections** — `List`/`Set` whose element type is not `String` or `Long`
+  (for example `List<Integer>`, `List<UUID>`, `List<LocalDate>`, `List<MyEnum>`, `List<MyPojo>`).
+- **Typed-value maps** — a `Map` value type other than `String`/`Object`
+  (for example `Map<String,Integer>`, `Map<String,UUID>`, `Map<String,MyPojo>`).
+- **Non-`String`/non-enum map keys** — for example `Map<Integer,Object>`, `Map<UUID,String>`.
+- **POJOs, records, and any other custom type.**
+
+> **Jackson marker annotation override:** if the property type carries a Jackson annotation
+> (anything meta-annotated with `com.fasterxml.jackson.annotation.JacksonAnnotation`), Ebean
+> uses the `ObjectMapper` path even when the type would otherwise be handled built-in.
+
+---
+
+## Adding `ebean-jackson-mapper`
+
+```xml
+<dependency>
+  <groupId>io.ebean</groupId>
+  <artifactId>ebean-jackson-mapper</artifactId>
+  <version>${ebean.version}</version>
+</dependency>
+```
+
+A Jackson `ObjectMapper` must be available (via `jackson-databind`). Ebean detects it and
+registers the mapper-based JSON support automatically.
+
+---
+
+## Notes
+
+- **Enum map keys** are serialised using the enum `name()` (for example `ACTIVE`), not any
+  `@DbEnumValue` mapping. Round-trips are correct; the DB value mapping is not applied to
+  JSON keys.
+- **`@DbArray` alternative:** for typed *scalar* collections (`List`/`Set` of `Integer`,
+  `Long`, `UUID`, `Double`, an enum, …) consider `@DbArray`, which maps to a native DB array
+  (with a JSON fallback on platforms without array support) and supports more element types
+  than built-in `@DbJson` collections.
+- The reason typed value/element collections need a real mapper is that the built-in path
+  only produces natural JSON types — for example a JSON number always parses to `Long`, so a
+  declared `List<Integer>` or `Map<String,Integer>` could not be populated safely without a
+  type-aware mapper.
+
+---
+
+## Choosing
+
+- Prefer the **built-in** mappings for the common cases (`String`, string/long lists and sets,
+  object/string maps) to avoid pulling in Jackson.
+- Add **`ebean-jackson-mapper`** when you need rich POJO JSON columns or typed collections /
+  typed-value maps.

docs/guides/migrating-json-jackson-core-to-avaje-json-core.md

@@ -0,0 +1,91 @@
+# Guide: Migrate JSON APIs from Jackson core to avaje-json-core
+
+## Purpose
+
+This guide covers the one-step cutover in Ebean from Jackson core JSON APIs to
+avaje-json-core APIs.
+
+Use this when upgrading code that references:
+
+- `com.fasterxml.jackson.core.JsonParser`
+- `com.fasterxml.jackson.core.JsonGenerator`
+- `com.fasterxml.jackson.core.JsonFactory`
+
+The replacement types are:
+
+- `io.avaje.json.JsonReader`
+- `io.avaje.json.JsonWriter`
+- `io.avaje.json.stream.JsonStream`
+
+---
+
+## Breaking API changes
+
+| Previous API | New API |
+|---|---|
+| `JsonParser` | `JsonReader` |
+| `JsonGenerator` | `JsonWriter` |
+| `JsonFactory` | `JsonStream` |
+| `DatabaseBuilder.jsonFactory(...)` | `DatabaseBuilder.jsonStream(...)` |
+| `DatabaseConfig.getJsonFactory()/setJsonFactory(...)` | `DatabaseConfig.getJsonStream()/setJsonStream(...)` |
+
+---
+
+## Typical migration rewrites
+
+### Parser and generator signatures
+
+```java
+// before
+void read(JsonParser parser)
+void write(JsonGenerator generator)
+
+// after
+void read(JsonReader parser)
+void write(JsonWriter generator)
+```
+
+### Database configuration
+
+```java
+// before
+Database.builder().jsonFactory(factory)
+
+// after
+Database.builder().jsonStream(stream)
+```
+
+### JSON utility calls
+
+`EJson` and `JsonContext` APIs now operate on `JsonReader` and `JsonWriter` types.
+If your code was calling those APIs with Jackson core types, switch to avaje types.
+
+---
+
+## Dependency and module notes
+
+- `ebean-core` no longer requires a direct `jackson-core` dependency for JSON
+  parsing/writing.
+- `jackson-databind` remains optional for `ObjectMapper` compatibility paths.
+- `ebean-jackson-mapper` remains the compatibility bridge module for mapper-based
+  integrations.
+
+---
+
+## Behavior notes to verify during upgrade
+
+1. Parser token handling is now based on avaje `JsonReader.Token`.
+2. Scalar JSON reads (for example booleans, date-time, array scalar types) should
+   be validated in your tests if you previously depended on Jackson token quirks.
+3. If your integration uses transient assoc-many JSON mapping with ObjectMapper,
+   keep ObjectMapper wiring enabled.
+
+---
+
+## Validation checklist
+
+1. Compile all modules that implement or consume `io.ebean.text.json` APIs.
+2. Run module tests that cover JSON scalar conversion and bean JSON round-trips.
+3. Confirm no remaining `com.fasterxml.jackson.core.*` imports in migrated code.
+4. Keep `ObjectMapper` compatibility tests if your project depends on mapper paths.
+

ebean-api/pom.xml

@@ -70,15 +70,13 @@
       <optional>true</optional>
     </dependency>
 
-    <!-- Jackson core used internally by Ebean -->
     <dependency>
-      <groupId>com.fasterxml.jackson.core</groupId>
-      <artifactId>jackson-core</artifactId>
-      <version>${jackson.version}</version>
-      <optional>true</optional>
+      <groupId>io.avaje</groupId>
+      <artifactId>avaje-json-core</artifactId>
+      <version>${avaje-json-core.version}</version>
     </dependency>
 
-    <!-- provided scope for JsonNode support -->
+    <!-- Jackson databind remains for ObjectMapper compatibility paths -->
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>

ebean-api/src/main/java/io/ebean/DatabaseBuilder.java

@@ -1,6 +1,6 @@
 package io.ebean;
 
-import com.fasterxml.jackson.core.JsonFactory;
+import io.avaje.json.stream.JsonStream;
 import io.ebean.annotation.*;
 import io.ebean.cache.ServerCachePlugin;
 import io.ebean.config.*;
@@ -360,18 +360,18 @@ default DatabaseBuilder slowQueryListener(SlowQueryListener slowQueryListener) {
   DatabaseBuilder putServiceObject(Object configObject);
 
   /**
-   * Set the Jackson JsonFactory to use.
+   * Set the JsonStream to use.
    * <p>
    * If not set a default implementation will be used.
    */
-  default DatabaseBuilder jsonFactory(JsonFactory jsonFactory) {
-    return setJsonFactory(jsonFactory);
+  default DatabaseBuilder jsonStream(JsonStream jsonStream) {
+    return setJsonStream(jsonStream);
   }
 
   /**
-   * @deprecated migrate to {@link #jsonFactory(JsonFactory)}.
+   * @deprecated migrate to {@link #jsonStream(JsonStream)}.
    */
-  DatabaseBuilder setJsonFactory(JsonFactory jsonFactory);
+  DatabaseBuilder setJsonStream(JsonStream jsonStream);
 
   /**
    * Set the JSON format to use for DateTime types.
@@ -2254,11 +2254,11 @@ interface Settings extends DatabaseBuilder {
     boolean isAutoLoadModuleInfo();
 
     /**
-     * Return the Jackson JsonFactory to use.
+     * Return the JsonStream to use.
      * <p>
      * If not set a default implementation will be used.
      */
-    JsonFactory getJsonFactory();
+    JsonStream getJsonStream();
 
     /**
      * Get the clock used for setting the timestamps (e.g. @UpdatedTimestamp) on objects.

ebean-api/src/main/java/io/ebean/config/ClassLoadConfig.java

@@ -60,7 +60,8 @@ public boolean isJacksonAnnotationsPresent() {
   }
 
   public boolean isJacksonCorePresent() {
-    return isPresent("com.fasterxml.jackson.core.JsonParser");
+    // Legacy method name retained for compatibility; now checks avaje JSON core.
+    return isPresent("io.avaje.json.JsonReader");
   }
 
   /**
@@ -158,4 +159,3 @@ ClassLoader getClassLoader() {
     }
   }
 }
-

ebean-api/src/main/java/io/ebean/config/DatabaseConfig.java

@@ -1,7 +1,7 @@
 package io.ebean.config;
 
-import com.fasterxml.jackson.core.JsonFactory;
 import io.avaje.config.Config;
+import io.avaje.json.stream.JsonStream;
 import io.ebean.*;
 import io.ebean.annotation.MutationDetection;
 import io.ebean.annotation.PersistBatch;
@@ -420,7 +420,7 @@ public class DatabaseConfig implements DatabaseBuilder.Settings {
    * The default PersistenceContextScope used if one is not explicitly set on a query.
    */
   private PersistenceContextScope persistenceContextScope = PersistenceContextScope.TRANSACTION;
-  private JsonFactory jsonFactory;
+  private JsonStream jsonStream;
   private boolean localTimeWithNanos;
   private boolean durationWithNanos;
   private int maxCallStack = 5;
@@ -631,13 +631,13 @@ private String serviceObjectKey(Class<?> cls) {
   }
 
   @Override
-  public JsonFactory getJsonFactory() {
-    return jsonFactory;
+  public JsonStream getJsonStream() {
+    return jsonStream;
   }
 
   @Override
-  public DatabaseConfig setJsonFactory(JsonFactory jsonFactory) {
-    this.jsonFactory = jsonFactory;
+  public DatabaseConfig setJsonStream(JsonStream jsonStream) {
+    this.jsonStream = jsonStream;
     return this;
   }