This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cayenne.git
The following commit(s) were added to refs/heads/master by this push:
new e88301255 organizing CLAUDE.md
e88301255 is described below
commit e883012550dc266e5e892b6703b5711512896112
Author: Andrus Adamchik <[email protected]>
AuthorDate: Sat May 9 15:27:56 2026 -0400
organizing CLAUDE.md
---
.claude/rules/cayenne/architecture.md | 51 +++++++++++++++++++++++++++++++++++
CLAUDE.md | 50 +++++-----------------------------
2 files changed, 57 insertions(+), 44 deletions(-)
diff --git a/.claude/rules/cayenne/architecture.md
b/.claude/rules/cayenne/architecture.md
new file mode 100644
index 000000000..54a6893cd
--- /dev/null
+++ b/.claude/rules/cayenne/architecture.md
@@ -0,0 +1,51 @@
+---
+paths:
+ - "cayenne/**"
+description: cayenne core module architecture, conventions, and test
infrastructure
+---
+
+## Architecture
+
+### Core Abstractions
+
+- **`CayenneRuntime`** — Entry point; manages lifecycle and wires together all
components via `cayenne-di`
+- **`ObjectContext`** — Primary user-facing API for CRUD operations; tracks
object changes and commits transactions
+- **`DataChannel`** / **`DataDomain`** — Sits between `ObjectContext` and the
database; routes queries and manages caching
+- **`DataNode`** — Represents a physical database connection (datasource +
adapter)
+- **`DbAdapter`** — Database-specific SQL generation; implementations in
`org.apache.cayenne.dba.*` (MySQL, PostgreSQL, Oracle, etc.)
+
+### Query API
+
+- **`ObjectSelect`** — Modern fluent API for fetching persistent objects
(preferred)
+- **`SQLSelect`** / **`SQLExec`** — Raw SQL with Cayenne parameter binding
+- **`EJBQLQuery`** — Legacy EJBQL support
+- **`Expression`** / **`ExpressionFactory`** — In-memory and SQL predicate
building
+
+### ORM Mapping
+
+- Mapping metadata lives in `cayenne-project.xml` (project descriptor) and
`*.map.xml` files (per-DataMap); loaded at startup into `DataMap` /
`EntityResolver`
+- `ObjEntity` → Java class; `DbEntity` → database table; `ObjRelationship` /
`DbRelationship` → joins
+- Persistent classes extend `_Abstract*` superclasses generated by
`cayenne-cgen`; user subclasses those
+
+### Key Packages (inside `cayenne/src/main/java/org/apache/cayenne/`)
+
+| Package | Purpose |
+|------------------|-----------------------------------------------------|
+| `access/` | Database access layer, `DataDomain`, `DataContext` |
+| `configuration/` | Runtime bootstrap, XML config loading |
+| `query/` | All query types |
+| `exp/` | Expression/criteria parsing and evaluation |
+| `dba/` | Per-database SQL dialects and adapters |
+| `map/` | ORM mapping metadata (`DataMap`, `ObjEntity`, etc.) |
+| `runtime/` | `CayenneRuntime`, DI module wiring |
+| `tx/` | Transaction management |
+
+## Source Code Conventions
+
+- Package root: `org.apache.cayenne`
+- All source files must have the Apache License 2.0 header (enforced by Apache
RAT plugin)
+- Encoding: UTF-8 everywhere
+
+## Test Infrastructure
+
+Tests use a shared set of test mapping files and database scripts in
`cayenne/src/test/resources/`. The `DBHelper` and `UnitDbAdapter` utilities
handle database-specific test setup.
diff --git a/CLAUDE.md b/CLAUDE.md
index ffb537a06..b427992cf 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code)
when working with co
## Project Overview
-Apache Cayenne is a Java ORM and persistence framework. This is a multi-module
Maven project (22 modules) targeting Java 21+.
+Apache Cayenne is a Java ORM and persistence framework. This is a multi-module
Maven project targeting Java 21+.
## Build Commands
@@ -55,54 +55,16 @@ mvn test -Dtest=SomeTest -DcayenneTestConnection=h2
- **cayenne-crypto**, **cayenne-commitlog**, **cayenne-lifecycle**,
**cayenne-jcache**, **cayenne-cache-invalidation** — Optional extension modules
- **modeler** — CayenneModeler GUI application (Swing)
-## Architecture
-### Core Abstractions
+## Test Style
-- **`CayenneRuntime`** — Entry point; manages lifecycle and wires together all
components via `cayenne-di`
-- **`ObjectContext`** — Primary user-facing API for CRUD operations; tracks
object changes and commits transactions
-- **`DataChannel`** / **`DataDomain`** — Sits between `ObjectContext` and the
database; routes queries and manages caching
-- **`DataNode`** — Represents a physical database connection (datasource +
adapter)
-- **`DbAdapter`** — Database-specific SQL generation; implementations in
`org.apache.cayenne.dba.*` (MySQL, PostgreSQL, Oracle, etc.)
-
-### Query API
-
-- **`ObjectSelect`** — Modern fluent API for fetching persistent objects
(preferred)
-- **`SQLSelect`** / **`SQLExec`** — Raw SQL with Cayenne parameter binding
-- **`EJBQLQuery`** — Legacy EJBQL support
-- **`Expression`** / **`ExpressionFactory`** — In-memory and SQL predicate
building
-
-### ORM Mapping
-
-- Mapping metadata lives in `cayenne-project.xml` (project descriptor) and
`*.map.xml` files (per-DataMap); loaded at startup into `DataMap` /
`EntityResolver`
-- `ObjEntity` → Java class; `DbEntity` → database table; `ObjRelationship` /
`DbRelationship` → joins
-- Persistent classes extend `_Abstract*` superclasses generated by
`cayenne-cgen`; user subclasses those
-
-### Key Packages (inside `cayenne/src/main/java/org/apache/cayenne/`)
-
-| Package | Purpose |
-|------------------|-----------------------------------------------------|
-| `access/` | Database access layer, `DataDomain`, `DataContext` |
-| `configuration/` | Runtime bootstrap, XML config loading |
-| `query/` | All query types |
-| `exp/` | Expression/criteria parsing and evaluation |
-| `dba/` | Per-database SQL dialects and adapters |
-| `map/` | ORM mapping metadata (`DataMap`, `ObjEntity`, etc.) |
-| `runtime/` | `CayenneRuntime`, DI module wiring |
-| `tx/` | Transaction management |
-
-### Source Code Conventions
-
-- Package root: `org.apache.cayenne`
-- All source files must have the Apache License 2.0 header (enforced by Apache
RAT plugin)
-- Encoding: UTF-8 everywhere
+Test naming: `*Test.java` = unit tests (Surefire), `*IT.java` = integration
tests (Failsafe).
+All new tests must use JUnit 5. Test classes and methods must be `public`.
Method names must not use the `test` prefix (e.g. `someFeature()` not
`testSomeFeature()`).
-### Test Infrastructure
+### Legacy Tests
-Tests in `cayenne/src/test/` use a shared set of test mapping files and
database scripts in `src/test/resources/`. The `DBHelper` and `UnitDbAdapter`
utilities handle database-specific test setup. TestContainers is used for
non-embedded databases.
-Test naming: `*Test.java` = unit tests (Surefire), `*IT.java` = integration
tests (Failsafe).
+JUnit 4 tests are still present but are considered legacy (run via
`junit-vintage-engine`). They are being migrated to JUnit 5. Mockito is used
for mocking and is also considered legacy and should be avoided in the new
tests.
-**Test style:** JUnit 5 is the standard for all new tests. JUnit 4-style tests
are legacy. New test classes and methods must be `public`; method names must
not use the `test` prefix (e.g., use `someFeature()` not `testSomeFeature()`).
Mockito is used for mocking for legacy reasons. Should avoid it in newer tests
## CI Matrix
