|
| 1 | +<!-- |
| 2 | + Licensed to the Apache Software Foundation (ASF) under one |
| 3 | + or more contributor license agreements. See the NOTICE file |
| 4 | + distributed with this work for additional information |
| 5 | + regarding copyright ownership. The ASF licenses this file |
| 6 | + to you under the Apache License, Version 2.0 (the |
| 7 | + "License"); you may not use this file except in compliance |
| 8 | + with the License. You may obtain a copy of the License at |
| 9 | + |
| 10 | + https://www.apache.org/licenses/LICENSE-2.0 |
| 11 | + |
| 12 | + Unless required by applicable law or agreed to in writing, |
| 13 | + software distributed under the License is distributed on an |
| 14 | + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 15 | + KIND, either express or implied. See the License for the |
| 16 | + specific language governing permissions and limitations |
| 17 | + under the License. |
| 18 | +--> |
| 19 | +# Obj-layer naming conventions — what to fix, what to leave alone |
| 20 | + |
| 21 | +Reference for the `cayenne-model-naming` skill. The governing rule: **the Modeler already |
| 22 | +generates good names for the common case. This is a polish pass, not a rewrite.** Read the |
| 23 | +"deterministic baseline" first so you can recognize a name that is already correct and skip it. |
| 24 | + |
| 25 | +## The deterministic baseline (leave these names alone) |
| 26 | + |
| 27 | +Reverse engineering (`dbimport_run`, the Modeler's DB Import) generates the Obj-layer names before |
| 28 | +you ever see the model, then de-duplicates any collisions. It already applies these principles — and |
| 29 | +you must preserve them: |
| 30 | + |
| 31 | +1. **Obj names stay as close to the DB names as possible** — the object name is a transliteration |
| 32 | + of the table/column, not a re-invention. |
| 33 | +2. **Java identifier / class conventions** — classes PascalCase, properties camelCase. |
| 34 | +3. **snake_case → camelCase / PascalCase** — split on `_`, drop the underscores, camel-join. |
| 35 | +4. **Relationship names from entity name + cardinality** — see below. |
| 36 | + |
| 37 | +Concretely, the generator produces: |
| 38 | + |
| 39 | +| DB element | Rule | Result | |
| 40 | +|---|---|---| |
| 41 | +| `db-entity` name | stem, split on `_`, capitalize each token | `ARTIST_GROUP` → `ArtistGroup` | |
| 42 | +| `db-attribute` name | split on `_`, camelCase | `FIRST_NAME` → `firstName` | |
| 43 | +| to-one relationship | FK column minus trailing `_ID`/`ID`; else target entity name | `MANAGER_ID` → `manager` | |
| 44 | +| to-many relationship | English plural of the target entity name | `PAINTING` → `paintings` | |
| 45 | +| name collision within an entity | append a numeric suffix | `team`, `team1`, `team2` … | |
| 46 | + |
| 47 | +Generation also collapses all-upper tokens to lowercase and preserves already-mixed |
| 48 | +case. So `GameType`, `gameType`, `firstName`, `ArtistGroup`, `paintings`, `manager` are **all |
| 49 | +already correct** — do not re-case, re-spell, re-pluralize, or "prettify" them. If a name is a |
| 50 | +clean camelCase/PascalCase transliteration of its DB element with the right cardinality, it is |
| 51 | +done. Touch nothing. |
| 52 | + |
| 53 | +## Where the deterministic algorithm falls short — the AI job |
| 54 | + |
| 55 | +The cases below are the ones we've identified where the generator can't do better and your judgment |
| 56 | +adds real value. They are **illustrative, not exhaustive** — the generator is a deterministic |
| 57 | +transliteration, so any place where a *human* reading the DB name would produce a clearly better |
| 58 | +Java name than a mechanical `_`-split is fair game (§5). Focus your attention on these gaps; don't |
| 59 | +touch names the baseline already got right. |
| 60 | + |
| 61 | +### 1. Run-together DB names with no separators |
| 62 | + |
| 63 | +Word-splitting happens **only on `_`**. A single-token, uniform-case DB name has no boundary to |
| 64 | +split on, so a multi-word concept collapses into one lowercased chunk. This is the classic case: |
| 65 | + |
| 66 | +| DB name | Generator output | Correct | |
| 67 | +|---|---|---| |
| 68 | +| `gametype` / `GAMETYPE` | `Gametype` | `GameType` | |
| 69 | +| `dateofbirth` | `Dateofbirth` | `dateOfBirth` | |
| 70 | +| `ordernumber` | `Ordernumber` | `orderNumber` | |
| 71 | +| `custaddr` | `Custaddr` | `CustomerAddress` (with expansion — see §3) | |
| 72 | + |
| 73 | +Split on the **real** word boundary, using domain knowledge, and re-apply the Java convention |
| 74 | +(PascalCase for entities, camelCase for attributes and relationships). Only split where you are confident a boundary |
| 75 | +exists — never invent one (`status` is not `sta` + `tus`; `metadata` is one word). Names that are |
| 76 | +**already** mixed-case (`GameType`, `gameType`) were handled by the generator — leave them. |
| 77 | + |
| 78 | +### 2. More than one relationship between the same two tables |
| 79 | + |
| 80 | +When two FKs point at the same target table (or two relationships otherwise share a target), |
| 81 | +generation can't invent a role, so it disambiguates with numbers. But **the two |
| 82 | +directions are not equally affected** — the to-one and to-many sides are named by different rules: |
| 83 | + |
| 84 | +- **to-many side always collides.** To-many naming ignores the FK column entirely and always uses |
| 85 | + the pluralized target entity name, so two relationships to the same target both become e.g. |
| 86 | + `games` / `games1` (or `people` / `people1`) no matter how well the FKs are named. This is the |
| 87 | + common case and the main reason this rule exists. Name each collection by the **logically opposite** |
| 88 | + role instead: on `Team`, the two reverse collections of `Game` become `homeGames` / `awayGames`. |
| 89 | + |
| 90 | +- **to-one side usually does NOT collide.** To-one naming is FK-column-based — it strips a trailing |
| 91 | + `_ID`/`ID`, so distinct `*_ID` FKs already yield distinct, good names (`HOME_TEAM_ID` → `homeTeam`, |
| 92 | + `AWAY_TEAM_ID` → `awayTeam`). Leave those alone. It **only** collides in the fallback path: when a |
| 93 | + FK column does *not* end in `ID`/`_ID` (or is null / has no joins), the generator drops to the |
| 94 | + target entity name, so two such FKs both become e.g. `employee` / `employee1`. There, derive the |
| 95 | + role from the FK column yourself even though it lacks the `_ID` suffix (`MANAGER` → `manager`, |
| 96 | + `SUPERVISOR` → `supervisor`). |
| 97 | + |
| 98 | +So in the typical "two well-named `*_ID` FKs" model you'll rename **only the to-many collections** |
| 99 | +(`games`/`games1`), and the to-one ends are already fine. When you do rename both ends, give them |
| 100 | +matching opposite-role names so the pair is legible from either side (`homeTeam` ↔ `homeGames`, |
| 101 | +`awayTeam` ↔ `awayGames`). |
| 102 | + |
| 103 | +### 3. Genuinely cryptic abbreviations (secondary, be conservative) |
| 104 | + |
| 105 | +Expand an abbreviation only when the win is clear **and** you apply it consistently across the whole |
| 106 | +model: `qty` → `quantity`, `amt` → `amount`, `dob` → `dateOfBirth`. An unfamiliar or ambiguous |
| 107 | +abbreviation stays as-is (case-normalized) rather than becoming a wrong guess. If the model is full |
| 108 | +of domain-specific abbreviations, ask the user for a glossary instead of guessing element by element. |
| 109 | + |
| 110 | +### 4. A common entity prefix leaking into relationship names |
| 111 | + |
| 112 | +Many schemas tag every table with the same prefix (`AA_CUSTOMER`, `AA_ORDER`, or `os_t1`, `os_t2`). |
| 113 | +The reverse-engineering **"Strip from Table Names"** (`stripFromTableNames`) setting handles this |
| 114 | +cleanly *when it's used*: entity names come through stripped (`AA_CUSTOMER` → `Customer`) and there's |
| 115 | +no problem — leave that model alone. |
| 116 | + |
| 117 | +The case that needs you is when the prefix is **kept on the entity names** (stripping was not |
| 118 | +configured — often intentional, treating the prefix as a class-name namespace). Then the prefix |
| 119 | +**leaks into the relationship names**, which you almost never want: |
| 120 | + |
| 121 | +- to-many names are the pluralized target entity name; with the prefix kept, the target's prefixed |
| 122 | + name flows straight in → `aaOrders`, `aaCustomers`. |
| 123 | +- to-one names built from a prefixed FK column (`AA_CUSTOMER_ID`) carry it too → `aaCustomer`. |
| 124 | + |
| 125 | +A relationship name is a **role/property** on a class (`order.getAaCustomer()`), and the shared |
| 126 | +prefix is pure noise there. **Strip the common prefix from the relationship names** — `aaOrders` → |
| 127 | +`orders`, `aaCustomer` → `customer` — and mirror the change onto the paired DbRelationship. |
| 128 | + |
| 129 | +**Leave the ObjEntity names as they are.** The prefix on the class names is the user's choice (if |
| 130 | +they'd wanted it gone from entities they would have set `stripFromTableNames`); renaming entities is |
| 131 | +a bigger, class-regenerating change. This case cleans relationship names only. |
| 132 | + |
| 133 | +### 5. Other cases — use judgment |
| 134 | + |
| 135 | +The three cases above don't exhaust the ways a purely mechanical transliteration can miss. Whenever |
| 136 | +you spot a name where a human reading the underlying DB name would obviously do better, and the fix |
| 137 | +is defensible (not a guess), apply the same conservative treatment. Some more examples: |
| 138 | + |
| 139 | +- **Reserved words / illegal identifiers** the generator passed through — a column literally named |
| 140 | + `class`, `package`, `default`, or one starting with a digit needs a legal Java name. |
| 141 | +- **Lost acronym casing** — `HTTPURL` → `Gametype`-style collapse loses the acronym; `httpUrl` / |
| 142 | + `url` may read better than `httpurl`. |
| 143 | +- **Plural table → singular entity** — a `CUSTOMERS` table yields `Customers`; an entity is a single |
| 144 | + row, so `Customer` is usually the intent (be careful: only when clearly a pluralized table name, |
| 145 | + and check for a resulting collision). |
| 146 | +- **Redundant entity-name prefix on an attribute** — `Artist.artistName` → `name` — only when it's |
| 147 | + clearly noise and doesn't collide. |
| 148 | + |
| 149 | +The bar is the same throughout: a clear, defensible improvement over the mechanical output, applied |
| 150 | +consistently. When in doubt, leave the baseline name and surface the question to the user rather than |
| 151 | +guessing. |
| 152 | + |
| 153 | +## Target forms (for the names you actually change) |
| 154 | + |
| 155 | +- **ObjEntity `name`** — PascalCase, singular preferred; keep it equal to the `className` simple name. |
| 156 | +- **ObjAttribute `name`** — camelCase; strip type/Hungarian prefixes (`strName` → `name`, `n_count` |
| 157 | + → `count`) only when unambiguous. |
| 158 | +- **ObjRelationship, to-one** — singular camelCase role. |
| 159 | +- **ObjRelationship, to-many** — plural camelCase. |
| 160 | +- **DbRelationship `name`** — mirror the paired ObjRelationship name (see below). |
| 161 | + |
| 162 | +## DbRelationship names |
| 163 | + |
| 164 | +A DbRelationship name is **arbitrary** — there is no DB metadata behind it (unlike a DbEntity/ |
| 165 | +DbAttribute, which mirror a real table/column). The working convention is that a DbRelationship's |
| 166 | +name matches the ObjRelationship built on it, **per direction**. So when you rename a to-one |
| 167 | +ObjRelationship to `homeTeam`, rename its backing single-hop DbRelationship to `homeTeam` as well, |
| 168 | +and the reverse-direction pair (`homeGames`) likewise. |
| 169 | + |
| 170 | +Flattened (many-to-many) ObjRelationships traverse more than one DbRelationship |
| 171 | +(`db-relationship-path="artistGroupArray.toArtist"`), so there is no 1:1 name to mirror — just keep |
| 172 | +each individual DbRelationship name sane on its own and fix any that are numbered collisions. |
| 173 | + |
| 174 | +See `model-naming-rename-safety.md` for exactly what to update when you rename any of these. |
0 commit comments