# Cayenne Cgen

> Use this skill whenever the user wants to (re)generate Cayenne entity Java classes from a DataMap. Trigger on phrases like 'generate Java classes', 'regenerate entities', 'run cgen', 'create the entity classes', 'why is the Artist class missing fields', 'where did the `_Abstract*` classes come from', 'sync the entity classes with the model', or any request to materialize Java from the DataMap. Also trigger as a follow-up after modeling changes (someone added an entity, attribute, or relationship and now the Java side is stale). This skill exclusively uses the `mcp__cayenne__cgen_run` MCP tool — it does NOT use `mvn cayenne:cgen` or the Gradle cgen task.

- Skill: `apache/cayenne-cgen` (Agent Skill)
- Install (CLI): `npx skillmds@latest add apache/cayenne-cgen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/apache/cayenne-cgen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: apache (https://skillmd.com/u/apache)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/apache/cayenne-cgen

---


<!--
	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-cgen

Run Cayenne's class generator on a DataMap via the `mcp__cayenne__cgen_run` MCP tool. The tool reads the embedded `<cgen>` block in the DataMap to determine destination, mode, templates, etc.; **if no block is present the tool generates anyway using a sensible default config** (all entities, `makePairs=true`, destination derived from the Maven layout). A missing `<cgen>` block is **not** an error and must never stop you from running the tool.

## Required reading

- `${CLAUDE_PLUGIN_ROOT}/references/mcp-tools.md` — `cgen_run` tool reference (arguments, return shape, failure modes).
- `${CLAUDE_PLUGIN_ROOT}/references/cgen-config.md` — every `<cgen>` field; needed when the user has to add or tweak the config block.
- `${CLAUDE_PLUGIN_ROOT}/references/project-layout.md` — locate the project descriptor.

## Step 1 — Resolve project and DataMap

The MCP tool needs two arguments:

- `projectPath` — **absolute path** to the top-level project descriptor (`cayenne-*.xml`). **Not** a DataMap file.
- `dataMap` — the **name** as it appears in `<map name="...">` in the descriptor. **Not** a file path.

Locate the descriptor via `project-layout.md`. If multiple descriptors exist, ask which one. Open the descriptor to extract the DataMap names from `<map>` elements.

If the user named the DataMap directly (e.g. "regenerate classes for the customers DataMap"), use that. If they said "regenerate everything" and there are multiple DataMaps, run `cgen_run` once per DataMap in sequence (the tool generates per-DataMap).

## Step 2 — Call `cgen_run`

```
mcp__cayenne__cgen_run({
  "projectPath": "<absolute path to cayenne-*.xml>",
  "dataMap": "<map name from the descriptor>"
})
```

Call the tool directly for each DataMap — never inspect the DataMap for a `<cgen>` block first, and never treat its absence as a blocker. The tool generates with a default config when no block exists.

If the tool is not available (MCP server not registered), surface `cayenne-mcp-server/README.md` and stop. **Do not** suggest `mvn cayenne:cgen` or the Gradle cgen task.

## Step 3 — Surface the result

The tool returns structured JSON. Report:

- `summary.filesConsidered` and `summary.filesWritten` verbatim — these are the headline.
- The first few entries in `files` (relative paths). Full list is informational; offer to dump it if the user asks.
- `error`, when non-null — this is blocking. Read the message and explain in user terms (a missing entity class name, a bad template path, an invalid `<destDir>`, etc.).
- `resolved.destDir` — the absolute output directory. If the DataMap had no `<cgen>` block, the tool generated from a synthesized default; report this destination so the user can confirm it's right, and offer to persist a `<cgen>` block (via `cayenne-modeling`) if they want to customize destination, templates, or entity filtering.

cgen always runs in full, but rewrites a file only when the generated contents differ from what is on disk. So `files` is exactly what changed, and a `status` of `up_to_date` means the Java was already in sync with the model — say so plainly rather than implying work was skipped.

## Step 4 — Next steps

- If new `_<Entity>.java` superclass files were generated, gently remind the user not to edit those — they will be overwritten next run. User code goes in the matching `<Entity>.java` subclass.
- If the user just ran reverse engineering, this skill is the natural follow-up. Cross-link back to `cayenne-modeling` if they need to tweak names/types before regenerating.

## Anti-patterns

- **Do not** pre-check the DataMap for a `<cgen>` block before calling `cgen_run`, and **do not** add a block before running. A missing block is not an error — the tool generates with defaults. Only add a `<cgen>` block afterward if the user wants to persist or customize the config.
- **Do not** suggest Maven (`mvn cayenne:cgen`) or Gradle (`cayenneCgen`) goals when MCP is unavailable. Those build plugins are out of scope. Point at MCP setup instead.
- **Do not** edit `_<Entity>.java` files. Generated superclasses. Edit `<Entity>.java` subclasses.
- **Do not** confuse `projectPath` and `dataMap` arguments. `projectPath` is a file system path to `cayenne-*.xml`. `dataMap` is a logical name (e.g. `mydb`), not a path to `mydb.map.xml`.