Refactor ClassCache, ClassCacheEntry, MappingConverter, ObjectReferenceMapper, ObjectEmbedMapper to use IObjectMapper/IRecordConverter

- Replace IBaseAeroMapper with IObjectMapper in ClassCache, ClassCacheEntry,
  MappingConverter, ObjectReferenceMapper, ObjectEmbedMapper
- Remove policy storage (defaultPolicies, childrenPolicies, specificPolicies,
  determinePolicy, setDefaultPolicies, setReactiveDefaultPolicies) from ClassCache;
  moved to new PolicyCache singleton in legacy
- Remove policy constructor params and getter methods (getReadPolicy, getWritePolicy,
  getBatchPolicy, getQueryPolicy, getScanPolicy) from ClassCacheEntry
- Remove getBins, constructAndHydrate(Key,Record), hydrateFromRecord from ClassCacheEntry;
  add getKeyFieldName(), isKeyFieldStoredAsBin(), setGenerationValue() helpers
- Replace IAerospikeClient with RecordLoader in MappingConverter constructor;
  new AerospikeRecordLoader implements RecordLoader via IAerospikeClient
- Remove Key/Record convertToObject overloads from MappingConverter; keep
  map/list-based overloads and add resolveDependencies=false variant
- ObjectReferenceMapper uses mapper.getRecordLoader() for record fetches
- Add IRecordConverter core interface; IObjectMapper returns IRecordConverter
  (MappingConverter implements IRecordConverter)
- IBaseAeroMapper extends IObjectMapper with covariant MappingConverter return
- AeroMapper and ReactiveAeroMapper implement getRecordLoader(); use PolicyCache
  for policy lookups instead of ClassCacheEntry policy getters
- Also update TypeUtils, ListMapper, MapMapper, PropertyDefinition, MapperUtils
  and virtuallist classes to use IObjectMapper; fix BaseVirtualList write policy

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: agrgr

.github/copilot-instructions.md

@@ -0,0 +1,126 @@
+# Copilot Instructions for Aerospike Java Object Mapper
+
+## Running Java commands
+JAVA_HOME=/usr/lib/jvm/java-17-openjdk-arm64
+PATH=/usr/lib/jvm/java-17-openjdk-arm64/bin:$PATH
+
+## Build & Test
+
+```bash
+# Compile (skip tests)
+mvn compile -B
+
+# Run all tests (requires a running Aerospike server on localhost:3000)
+mvn clean test -B -U
+
+# Run a single test class
+mvn test -Dtest=AeroMapperTest -B
+
+# Run a single test method
+mvn test -Dtest=AeroMapperTest#testSimpleSave -B
+
+# Run tests against a different Aerospike host
+mvn test -Dtest.host=myhost:3000 -B
+```
+
+Java 8 source/target compatibility. No separate lint step.
+
+## Architecture
+
+This is an annotation-driven ORM that maps Java POJOs to Aerospike database records. 
+It has two parallel APIs: synchronous (`AeroMapper`) and reactive (`ReactiveAeroMapper`), 
+both built through the same `AbstractBuilder<T>` pattern.
+
+### Core data flow (sync)
+
+```
+Write path (Use-case → Aerospike):
+
+  save(obj) → ClassCacheEntry.getBins(obj) → IAerospikeClient.put(bins)
+
+   1. JavaMapperApplication → Entry point, calls mapper.save(customer)
+   2. AeroMapper → API layer, creates WritePolicy, extracts key, converts to bins
+   3. ClassCacheEntry<Customer> → Reflection engine, iterates fields, extracts values
+   4. TypeMapper → Converts Java types (Date, List) to Aerospike format (Long, Map)
+   5. AerospikeClient → SDK handles network I/O
+   6. Aerospike Server → Persists record in namespace "test", set "customer"
+
+Read path (Aerospike → Use-case):
+
+  read(Class<T>, key) → IAerospikeClient.get() → MappingConverter → ClassCacheEntry.hydrateFromRecord()
+
+   1. JavaMapperApplication → Calls mapper.read(Customer.class, "cust1")
+   2. AeroMapper → Constructs Key, checks cache, calls client.get()
+   3. AerospikeClient → Retrieves Record from server
+   4. Aerospike Server → Returns Record with bin data
+   5. MappingConverter → Orchestrates conversion
+   6. ClassCacheEntry<Customer> → Constructs Customer, iterates bins, populates fields (hydrateFromRecord())
+   7. TypeMapper → Converts Aerospike format back to Java types
+   8. Customer Object → Fully hydrated and returned
+
+VirtualList append path (e.g. appending an Item to a Container's embedded list):
+
+  mapper.asBackedList(container, "items", Item.class).append(new Item(500, new Date(), "Item5"))
+
+   1. AeroMapper.asBackedList(container, "items", Item.class) → Constructs VirtualList, resolves ClassCacheEntry for Container + Item, extracts ListMapper from the @AerospikeEmbed bin "items"
+   2. VirtualList.append(item) → Delegates to VirtualListInteractors
+   3. VirtualListInteractors.getAppendOperation() → ListMapper.toAerospikeInstanceFormat(item) converts Item to Aerospike-native format (Map/List depending on EmbedType)
+   4. VirtualListInteractors → Builds CDT operation: MapOperation.put(binName, key, value) for MAP embed, or ListOperation.append(binName, value) for LIST embed
+   5. AerospikeClient.operate(writePolicy, key, operation) → Sends CDT operation to server, atomically appends to the bin without reading the full list
+   6. Aerospike Server → Appends element server-side, returns updated bin size
+   7. VirtualList → Returns size (long); the in-memory container object is NOT updated
+
+VirtualList query path (e.g. getByKeyRange):
+
+  list.getByKeyRange(100, 450)
+
+   1. VirtualList.getByKeyRange(start, end) → Sets return type, delegates to VirtualListInteractors
+   2. VirtualListInteractors → Creates Interactor wrapping a DeferredOperation
+   3. DeferredOperation.getOperation() → Translates keys via ClassCacheEntry.translateKeyToAerospikeKey(), builds MapOperation.getByKeyRange(binName, startValue, endValue, returnType)
+   4. AerospikeClient.operate() → Sends CDT query to server
+   5. Aerospike Server → Evaluates range server-side, returns matching entries
+   6. Interactor.getResult() → Chains ResultsUnpackers (ArrayUnpacker iterates results, calls ListMapper.fromAerospikeInstanceFormat() per element)
+   7. MappingConverter.resolveDependencies() → Resolves any nested @AerospikeReference objects
+   8. VirtualList → Returns List<Item> of matched elements
+```
+
+### Key classes and their roles
+
+- **`AeroMapper` / `ReactiveAeroMapper`** — Public API entry points (sync returns objects, reactive returns `Mono`/`Flux`). Both are instantiated via their inner `Builder` class, never directly.
+- **`AbstractBuilder<T>`** — Shared builder logic: register custom type converters, preload classes, set policies, load YAML configuration.
+- **`ClassCacheEntry<T>`** — Parses annotations on a mapped class and caches the metadata (namespace, set, key field, bin names, policies). Lazily constructed. Used by the mapper to serialize/deserialize objects.
+- **`ClassCache`** — Singleton cache of `ClassCacheEntry` instances.
+- **`MappingConverter`** — Orchestrates type conversion during serialization/deserialization using registered `TypeMapper` instances.
+- **`TypeMapper`** — Abstract base for custom type converters. Override `toAerospikeFormat()` and `fromAerospikeFormat()`. Register via `builder.addConverter()`.
+
+### Annotation system (`com.aerospike.mapper.annotations`)
+
+- `@AerospikeRecord` — Marks a class as mappable; defines namespace, set, TTL.
+- `@AerospikeKey` — Designates the primary key field.
+- `@AerospikeBin` — Customizes bin (column) name for a field.
+- `@AerospikeEmbed` / `@AerospikeReference` — Relationship mapping (embedded vs. referenced sub-objects).
+- `@AerospikeExclude` — Excludes a field from mapping.
+- `@ToAerospike` / `@FromAerospike` — Custom per-field conversion methods.
+- `@AerospikeVersion` / `@AerospikeGeneration` — Optimistic concurrency control.
+- `@AerospikeConstructor` / `@ParamFrom` — Controls object construction from records.
+
+### Type mappers (`tools/mappers/`)
+
+Built-in mappers for Java primitives, `Date`, `Instant`, `LocalDate`, `LocalDateTime`, `BigDecimal`, `BigInteger`, 
+enums, arrays, lists, and maps. Custom mappers extend `TypeMapper`.
+
+### Virtual Lists (`tools/virtuallist/`)
+
+Aerospike CDT-backed lists that support lazy loading and server-side operations without retrieving entire collections. 
+Both sync (`VirtualList`) and reactive (`ReactiveVirtualList`) variants exist.
+
+### Configuration (`tools/configuration/`)
+
+Alternative to annotations: YAML-based configuration for class mappings via `builder.withConfiguration()`.
+
+## Conventions
+
+- **Package root**: `com.aerospike.mapper` — annotations, exceptions, and `tools` sub-packages.
+- **Lombok**: Used in production code (provided scope). Ensure IDE/build has Lombok support.
+- **Test base classes**: Sync tests extend `AeroMapperBaseTest`; reactive tests extend `ReactiveAeroMapperBaseTest`. Both handle client lifecycle and provide a `compare()` helper that uses Jackson for JSON-based object comparison.
+- **Test setup**: Each test method gets a fresh `AeroMapper` via `Builder` and clears `ClassCache` in `@BeforeEach`. Tables are truncated before tests to ensure isolation.

core/pom.xml

@@ -0,0 +1,69 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<groupId>com.aerospike</groupId>
+		<artifactId>java-object-mapper-parent</artifactId>
+		<version>2.6.0</version>
+	</parent>
+
+	<artifactId>java-object-mapper-core</artifactId>
+	<packaging>jar</packaging>
+
+	<name>Aerospike Object Mapper Core</name>
+	<description>Core annotation-processing and type-mapping engine with no Aerospike client dependency.</description>
+
+	<dependencies>
+		<dependency>
+		    <groupId>javax.validation</groupId>
+		    <artifactId>validation-api</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.apache.commons</groupId>
+			<artifactId>commons-lang3</artifactId>
+		</dependency>
+		<dependency>
+		    <groupId>com.fasterxml.jackson.dataformat</groupId>
+		    <artifactId>jackson-dataformat-yaml</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.projectlombok</groupId>
+			<artifactId>lombok</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.junit.jupiter</groupId>
+			<artifactId>junit-jupiter</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.mockito</groupId>
+			<artifactId>mockito-core</artifactId>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<plugins>
+			<plugin>
+				<artifactId>maven-compiler-plugin</artifactId>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-dependency-plugin</artifactId>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-surefire-plugin</artifactId>
+			</plugin>
+		</plugins>
+		<resources>
+			<resource>
+				<directory>${project.basedir}/src/main/java</directory>
+				<includes>
+					<include>**/*.properties</include>
+					<include>**/*.xml</include>
+				</includes>
+			</resource>
+		</resources>
+	</build>
+</project>

core/src/main/java/com/aerospike/mapper/tools/IObjectMapper.java

@@ -0,0 +1,11 @@
+package com.aerospike.mapper.tools;
+
+/**
+ * Minimal contract that core-bound classes use to interact with the enclosing mapper.
+ * Implemented by both the legacy AeroMapper and the fluent FluentAeroMapper.
+ */
+public interface IObjectMapper {
+    IRecordConverter getMappingConverter();
+
+    RecordLoader getRecordLoader();
+}

core/src/main/java/com/aerospike/mapper/tools/IRecordConverter.java

@@ -0,0 +1,13 @@
+package com.aerospike.mapper.tools;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Core-level abstraction for converting Aerospike bin data to Java objects.
+ * Implemented by MappingConverter in the legacy module.
+ */
+public interface IRecordConverter {
+    <T> T convertToObject(Class<T> clazz, Map<String, Object> record);
+    <T> T convertToObject(Class<T> clazz, List<Object> record);
+}

core/src/main/java/com/aerospike/mapper/tools/RecordKey.java

@@ -0,0 +1,28 @@
+package com.aerospike.mapper.tools;
+
+/**
+ * Client-agnostic identifier for an Aerospike record.
+ * Used by RecordLoader for batch operations.
+ */
+public class RecordKey {
+    public final String namespace;
+    public final String setName;
+    /** User-key value; null when the record is identified by digest only. */
+    public final Object keyValue;
+    /** Pre-computed digest; null when the record is identified by keyValue. */
+    public final byte[] digest;
+
+    public RecordKey(String namespace, String setName, Object keyValue) {
+        this.namespace = namespace;
+        this.setName = setName;
+        this.keyValue = keyValue;
+        this.digest = null;
+    }
+
+    public RecordKey(String namespace, String setName, byte[] digest) {
+        this.namespace = namespace;
+        this.setName = setName;
+        this.keyValue = null;
+        this.digest = digest;
+    }
+}

core/src/main/java/com/aerospike/mapper/tools/RecordLoader.java

@@ -0,0 +1,26 @@
+package com.aerospike.mapper.tools;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Abstraction over the Aerospike client's record-fetch operations.
+ * Implemented by the legacy module (via IAerospikeClient) and the fluent module (via Session).
+ * Used by MappingConverter to resolve @AerospikeReference objects without a direct client dependency.
+ */
+public interface RecordLoader {
+    /**
+     * Fetch a single record by its user-key value. Returns null if not found.
+     */
+    Map<String, Object> getRecord(String namespace, String setName, Object keyValue);
+
+    /**
+     * Fetch a single record by its pre-computed digest. Returns null if not found.
+     */
+    Map<String, Object> getRecordByDigest(String namespace, String setName, byte[] digest);
+
+    /**
+     * Batch-fetch records. Entries with no matching record are returned as null in the list.
+     */
+    List<Map<String, Object>> getBatchRecords(List<RecordKey> keys);
+}

core/src/main/java/com/aerospike/mapper/tools/RecordMetaConfig.java

@@ -0,0 +1,24 @@
+package com.aerospike.mapper.tools;
+
+/**
+ * Holds annotation-derived per-class Aerospike record settings.
+ * Decouples ClassCacheEntry from legacy client policy types.
+ */
+public class RecordMetaConfig {
+    private int ttl = -1;
+    private Boolean sendKey = null;
+    private Boolean durableDelete = null;
+    private Boolean mapAll = null;
+
+    public int getTtl() { return ttl; }
+    public void setTtl(int ttl) { this.ttl = ttl; }
+
+    public Boolean getSendKey() { return sendKey; }
+    public void setSendKey(Boolean sendKey) { this.sendKey = sendKey; }
+
+    public Boolean getDurableDelete() { return durableDelete; }
+    public void setDurableDelete(Boolean durableDelete) { this.durableDelete = durableDelete; }
+
+    public Boolean getMapAll() { return mapAll; }
+    public void setMapAll(Boolean mapAll) { this.mapAll = mapAll; }
+}

fluent/pom.xml

@@ -0,0 +1,65 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<groupId>com.aerospike</groupId>
+		<artifactId>java-object-mapper-parent</artifactId>
+		<version>2.6.0</version>
+	</parent>
+
+	<artifactId>java-object-mapper-fluent</artifactId>
+	<packaging>jar</packaging>
+
+	<name>Aerospike Object Mapper Fluent</name>
+	<description>Aerospike Object Mapper using the new fluent Aerospike Java client. Implements RecordMapper and RecordMappingFactory.</description>
+
+	<dependencies>
+		<dependency>
+			<groupId>com.aerospike</groupId>
+			<artifactId>java-object-mapper-core</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>com.aerospike</groupId>
+			<artifactId>aerospike-client-fluent</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.projectlombok</groupId>
+			<artifactId>lombok</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.junit.jupiter</groupId>
+			<artifactId>junit-jupiter</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>org.mockito</groupId>
+			<artifactId>mockito-core</artifactId>
+		</dependency>
+	</dependencies>
+
+	<build>
+		<plugins>
+			<plugin>
+				<artifactId>maven-compiler-plugin</artifactId>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-dependency-plugin</artifactId>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-surefire-plugin</artifactId>
+			</plugin>
+		</plugins>
+		<resources>
+			<resource>
+				<directory>${project.basedir}/src/main/java</directory>
+				<includes>
+					<include>**/*.properties</include>
+					<include>**/*.xml</include>
+				</includes>
+			</resource>
+		</resources>
+	</build>
+</project>