cayenne-modeling

<!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> # cayenne-modeling Edit Cayenne DataMap (`*.map.xml`) and project descriptor (`cayenne-*.xml`) files directly. This is the **default path** for granular model changes — adding one entity, one relationship, one query. Use the Modeler GUI (`cayenne-modeler` skill) only for inherently visual work like reverse engineering. ## Required reading Read these before making any edit — they describe the XML formats this skill operates on: - `${CLAUDE_PLUGIN_ROOT}/references/project-layout.md` — locate the project descriptor and DataMaps in the user's repo. - `${CLAUDE_PLUGIN_ROOT}/references/datamap-schema.md` — every element shape for `*.map.xml`. - `${CLAUDE_PLUGIN_ROOT}/references/project-descriptor-schema.md` — `cayenne-*.xml` shape. ## Step 1 — Locate the right file Follow `project-layout.md`. If the user has multiple Cayenne projects and the request is ambiguous, ask which one. Cache the answer for the rest of the session. Decide whether the change belongs in a DataMap or the project descriptor (table at the end of `project-layout.md`): - Entity/relationship/query/embeddable/procedure → DataMap (`*.map.xml`). - DataMap list, DataNode (DB connection) → project descriptor (`cayenne-*.xml`). ## Step 2 — Make the edit Apply the change following the schema in `datamap-schema.md` or `project-descriptor-schema.md`. ### Critical rules 1. **Element order matters.** The DataMap schema requires this order inside `<dataMap>`: `<procedure>`, `<embeddable>`, `<dbEntity>`, `<objEntity>`, `<dbRelationship>`, `<objRelationship>`, the queries (`<objectQuery>`, `<sqlQuery>`, `<procedureQuery>`), `<cgen>`, `<dbImport>`. Insert at the right place — don't append blindly. 2. **Cross-link consistently.** - An `<objEntity>` references a `<dbEntity>` by `dbEntityName="..."`. Make sure that DbEntity exists. - An `<objAttribute>` references a DbAttribute by `dbAttributePath="COLUMN_NAME"`. Make sure that column exists on the DbEntity (or on a related one if using a dotted path through a relationship). - An `<objRelationship>` requires a backing `<dbRelationship>` (or chain of them) via `dbRelationshipPath`. Never add an ObjRelationship without the DB-layer counterpart. - Most FKs need **two** `<dbRelationship>` entries, one per direction. They are not auto-derived. 3. **Use the right `type` on attributes.** - `dbAttribute type` — JDBC type names: `VARCHAR`, `INTEGER`, `BIGINT`, `DATE`, `TIMESTAMP`, `BOOLEAN`, `NUMERIC`, `BLOB`, `CLOB`, `VARBINARY`, etc. VARCHAR/CHAR/VARBINARY also need `length`. NUMERIC/DECIMAL also need `scale`. - `objAttribute type` — Java FQN: `java.lang.String`, `java.lang.Integer`, `java.util.Date`, `java.math.BigDecimal`, `byte[]`, etc. Use wrapper types (`Integer`, not `int`) for nullable columns. 4. **PK handling.** PK columns get `primaryKey="true" mandatory="true"` on the DbAttribute. They are normally **not** mirrored as ObjAttributes — Cayenne handles them implicitly. Map a PK as an ObjAttribute only if the user wants a "meaningful PK" (visible on the Java side). 5. **Preserve formatting.** Match the indentation and quote style of the file (the standard Cayenne style uses tabs and double quotes, but follow what's actually in the file you're editing). 6. **Changing `defaultPackage` on a DataMap.** If the user asks to change the DataMap-level `defaultPackage` attribute, ask whether entity-level packages should be updated too. Otherwise, every existing `objEntity` will keep its old package. Ask: "Do you also want me to update the `className` values on individual `<objEntity>` elements that currently use the old package?" Update them only if the user confirms. ## Step 3 — Validate the edit conceptually After writing the XML, mentally walk through: - Does every `objEntity.dbEntityName` resolve to an existing `<dbEntity>`? - Does every `objAttribute.dbAttributePath` resolve to a column on the right DbEntity? - Does every `objRelationship.dbRelationshipPath` resolve to a chain of existing `<dbRelationship>` entries? - Are PK and FK columns marked `mandatory="true"` where the DB enforces NOT NULL? If anything fails, fix it before reporting done. ## Step 4 — Offer the right next step - **If you modified entities and the DataMap has a `<cgen>` block:** suggest invoking the `cayenne-cgen` skill to regenerate Java classes. Mention which entities are affected. - **If the user added a new entity and there's no Java class yet:** same — recommend `cayenne-cgen`. - **If the user is asking about a full DB sync** (importing many tables, syncing with a changed schema): hand off to `cayenne-db-import`. Do not try to script this via XML edits. - **If the request is about making names descriptive/consistent** (cleaning up reverse-engineered names, fixing `Gametype`/`team1`-style names, normalizing entity/attribute/relationship names across the model): hand off to `cayenne-model-naming` — it knows the naming conventions and the rename cross-reference checklist. - **If the change is structurally messy** (bulk renaming relationships, visual graph rework): suggest the `cayenne-modeler` skill. Otherwise do not. ## Modeler coexistence CayenneModeler **watches the project XML files** and automatically detects on-disk changes. When you edit a `*.map.xml` file directly, the Modeler will prompt the user to reload the project the next time they interact with it. There is no risk of the Modeler silently overwriting your edits. Do **not** warn the user that the Modeler may overwrite changes or tell them to close the Modeler before editing — that is incorrect and unnecessary. ## Anti-patterns - **Don't hand-edit `_<Entity>.java` superclass files.** They are regenerated by cgen and your changes will be overwritten. Edit the user `<Entity>.java` subclass instead. - **Don't add an `objRelationship` without a `dbRelationship`.** Cayenne will validate-fail at runtime. - **Don't use primitive Java types (`int`, `long`, `boolean`) as `objAttribute type` for nullable columns.** Primitives can't represent NULL. Use wrappers. - **Don't reorder existing elements.** The schema requires the order documented above; reordering existing elements may also create noisy diffs. - **Don't run cgen yourself.** That's `cayenne-cgen`'s job — invoke that skill instead of calling the MCP tool directly here. - **Don't suggest `mvn cayenne:cdbimport` or any Maven/Gradle plugin goal.** Those are explicitly out of scope for this plugin.