This is an automated email from the ASF dual-hosted git repository.
aadamchik 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 b7ee81eea Adding basic CLAUDE.md
b7ee81eea is described below
commit b7ee81eea2df26518d2df06b73fb2d7e275ff12b
Author: Andrus Adamchik <[email protected]>
AuthorDate: Sat Apr 11 08:51:51 2026 -0400
Adding basic CLAUDE.md
We will edit it as needed
---
CLAUDE.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 98 insertions(+)
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..1550c143d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
code in this repository.
+
+## Project Overview
+
+Apache Cayenne is a Java ORM and persistence framework. This is a multi-module
Maven project (22 modules) targeting Java 11+.
+
+## Build Commands
+
+```bash
+# Full build
+mvn clean verify
+
+# Skip tests
+mvn clean verify -DskipTests
+
+# Build a single module and its dependencies
+mvn clean verify -pl cayenne -am
+```
+
+## Testing
+
+The `cayenneTestConnection` property selects the database backend for tests.
Default is HSQL.
+
+```bash
+# Run all tests (HSQL)
+mvn verify
+
+# Run against specific databases
+mvn verify -DcayenneTestConnection=h2
+mvn verify -DcayenneTestConnection=derby
+mvn verify -DcayenneTestConnection=mysql-tc # via TestContainers
+mvn verify -DcayenneTestConnection=postgres-tc # via TestContainers
+mvn verify -DcayenneTestConnection=sqlserver-tc # via TestContainers
+
+# Run a single test class (in the relevant module directory)
+mvn test -Dtest=PoolingDataSourceTest
+
+# Run a single test method
+mvn test -Dtest=PoolingDataSourceTest#testConnection
+
+# Run a single test against a specific database
+mvn test -Dtest=SomeTest -DcayenneTestConnection=h2
+```
+
+CI runs JDK 11 and 17 with all database profiles on each PR.
+
+## Module Structure
+
+- **cayenne** — Core ORM library (main module to work with)
+- **cayenne-di** — Lightweight DI container used internally
+- **cayenne-project** — Cayenne project/model file management
+- **cayenne-cgen** — Code generation from database schemas
+- **cayenne-dbsync** — Database schema synchronization
+- **cayenne-gradle-plugin**, **maven-plugins**, **cayenne-ant** — Build tool
integrations
+- **cayenne-crypto**, **cayenne-commitlog**, **cayenne-lifecycle**,
**cayenne-jcache**, **cayenne-cache-invalidation** — Optional extension modules
+- **modeler** — CayenneModeler GUI application (Swing)
+
+## 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 |
+
+### Test Infrastructure
+
+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.
