Skip to content

Commit e883012

Browse files
andrusandrus
committed
organizing CLAUDE.md
1 parent 096d68a commit e883012

2 files changed

Lines changed: 57 additions & 44 deletions

File tree

‎.claude/rules/cayenne/architecture.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
paths:
3+
- "cayenne/**"
4+
description: cayenne core module architecture, conventions, and test infrastructure
5+
---
6+
7+
## Architecture
8+
9+
### Core Abstractions
10+
11+
- **`CayenneRuntime`** — Entry point; manages lifecycle and wires together all components via `cayenne-di`
12+
- **`ObjectContext`** — Primary user-facing API for CRUD operations; tracks object changes and commits transactions
13+
- **`DataChannel`** / **`DataDomain`** — Sits between `ObjectContext` and the database; routes queries and manages caching
14+
- **`DataNode`** — Represents a physical database connection (datasource + adapter)
15+
- **`DbAdapter`** — Database-specific SQL generation; implementations in `org.apache.cayenne.dba.*` (MySQL, PostgreSQL, Oracle, etc.)
16+
17+
### Query API
18+
19+
- **`ObjectSelect`** — Modern fluent API for fetching persistent objects (preferred)
20+
- **`SQLSelect`** / **`SQLExec`** — Raw SQL with Cayenne parameter binding
21+
- **`EJBQLQuery`** — Legacy EJBQL support
22+
- **`Expression`** / **`ExpressionFactory`** — In-memory and SQL predicate building
23+
24+
### ORM Mapping
25+
26+
- Mapping metadata lives in `cayenne-project.xml` (project descriptor) and `*.map.xml` files (per-DataMap); loaded at startup into `DataMap` / `EntityResolver`
27+
- `ObjEntity` → Java class; `DbEntity` → database table; `ObjRelationship` / `DbRelationship` → joins
28+
- Persistent classes extend `_Abstract*` superclasses generated by `cayenne-cgen`; user subclasses those
29+
30+
### Key Packages (inside `cayenne/src/main/java/org/apache/cayenne/`)
31+
32+
| Package | Purpose |
33+
|------------------|-----------------------------------------------------|
34+
| `access/` | Database access layer, `DataDomain`, `DataContext` |
35+
| `configuration/` | Runtime bootstrap, XML config loading |
36+
| `query/` | All query types |
37+
| `exp/` | Expression/criteria parsing and evaluation |
38+
| `dba/` | Per-database SQL dialects and adapters |
39+
| `map/` | ORM mapping metadata (`DataMap`, `ObjEntity`, etc.) |
40+
| `runtime/` | `CayenneRuntime`, DI module wiring |
41+
| `tx/` | Transaction management |
42+
43+
## Source Code Conventions
44+
45+
- Package root: `org.apache.cayenne`
46+
- All source files must have the Apache License 2.0 header (enforced by Apache RAT plugin)
47+
- Encoding: UTF-8 everywhere
48+
49+
## Test Infrastructure
50+
51+
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.

‎CLAUDE.md‎

Lines changed: 6 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
44

55
## Project Overview
66

7-
Apache Cayenne is a Java ORM and persistence framework. This is a multi-module Maven project (22 modules) targeting Java 21+.
7+
Apache Cayenne is a Java ORM and persistence framework. This is a multi-module Maven project targeting Java 21+.
88

99
## Build Commands
1010

@@ -55,54 +55,16 @@ mvn test -Dtest=SomeTest -DcayenneTestConnection=h2
5555
- **cayenne-crypto**, **cayenne-commitlog**, **cayenne-lifecycle**, **cayenne-jcache**, **cayenne-cache-invalidation** — Optional extension modules
5656
- **modeler** — CayenneModeler GUI application (Swing)
5757

58-
## Architecture
5958

60-
### Core Abstractions
59+
## Test Style
6160

62-
- **`CayenneRuntime`** — Entry point; manages lifecycle and wires together all components via `cayenne-di`
63-
- **`ObjectContext`** — Primary user-facing API for CRUD operations; tracks object changes and commits transactions
64-
- **`DataChannel`** / **`DataDomain`** — Sits between `ObjectContext` and the database; routes queries and manages caching
65-
- **`DataNode`** — Represents a physical database connection (datasource + adapter)
66-
- **`DbAdapter`** — Database-specific SQL generation; implementations in `org.apache.cayenne.dba.*` (MySQL, PostgreSQL, Oracle, etc.)
67-
68-
### Query API
69-
70-
- **`ObjectSelect`** — Modern fluent API for fetching persistent objects (preferred)
71-
- **`SQLSelect`** / **`SQLExec`** — Raw SQL with Cayenne parameter binding
72-
- **`EJBQLQuery`** — Legacy EJBQL support
73-
- **`Expression`** / **`ExpressionFactory`** — In-memory and SQL predicate building
74-
75-
### ORM Mapping
76-
77-
- Mapping metadata lives in `cayenne-project.xml` (project descriptor) and `*.map.xml` files (per-DataMap); loaded at startup into `DataMap` / `EntityResolver`
78-
- `ObjEntity` → Java class; `DbEntity` → database table; `ObjRelationship` / `DbRelationship` → joins
79-
- Persistent classes extend `_Abstract*` superclasses generated by `cayenne-cgen`; user subclasses those
80-
81-
### Key Packages (inside `cayenne/src/main/java/org/apache/cayenne/`)
82-
83-
| Package | Purpose |
84-
|------------------|-----------------------------------------------------|
85-
| `access/` | Database access layer, `DataDomain`, `DataContext` |
86-
| `configuration/` | Runtime bootstrap, XML config loading |
87-
| `query/` | All query types |
88-
| `exp/` | Expression/criteria parsing and evaluation |
89-
| `dba/` | Per-database SQL dialects and adapters |
90-
| `map/` | ORM mapping metadata (`DataMap`, `ObjEntity`, etc.) |
91-
| `runtime/` | `CayenneRuntime`, DI module wiring |
92-
| `tx/` | Transaction management |
93-
94-
### Source Code Conventions
95-
96-
- Package root: `org.apache.cayenne`
97-
- All source files must have the Apache License 2.0 header (enforced by Apache RAT plugin)
98-
- Encoding: UTF-8 everywhere
61+
Test naming: `*Test.java` = unit tests (Surefire), `*IT.java` = integration tests (Failsafe).
62+
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()`).
9963

100-
### Test Infrastructure
64+
### Legacy Tests
10165

102-
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.
103-
Test naming: `*Test.java` = unit tests (Surefire), `*IT.java` = integration tests (Failsafe).
66+
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.
10467

105-
**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
10668

10769
## CI Matrix
10870

0 commit comments

Comments
 (0)
⚡