Merge pull request #57 from abap2UI5/claude/add-locks-numbering-ulWaD

Restructure locking strategies guide with numbered sections and comparison table

Author: oblomov-dev

docs/development/specific/locks.md

@@ -12,10 +12,10 @@ In classic SAP GUI, a transaction like `VA02` calls `ENQUEUE_EVVBAK` and the loc
 
 The patterns below combine in different ways. The examples use the sales order header table `VBAK` and its standard enqueue object `EVVBAK`, but the same shapes apply to any table. All snippets have a complete, copy-paste-ready demo class — sample numbers are linked next to each section.
 
-#### No Locking
+#### 1. No Locking
 The minimal starting point — the user edits and saves, no lock and no conflict check. Last save wins, silently. Fine for personal sandboxes and throwaway demos, but rarely what you want in production. See sample `Z2UI5_CL_DEMO_APP_S_07`.
 
-#### Lock at Save
+#### 2. Lock at Save
 Do not hold a lock while the user thinks. Acquire it the moment they save, write, commit, and release — all in one short roundtrip:
 ```abap
 METHOD on_event_save.
@@ -49,7 +49,7 @@ ENDMETHOD.
 
 The lock exists for milliseconds, so this scales — but two parallel saves can still race if the timestamps line up, and the second one silently overwrites the first. See sample `Z2UI5_CL_DEMO_APP_S_08`.
 
-#### Optimistic Check
+#### 3. Optimistic Check
 On read, remember the record's change timestamp. On save, re-read and reject if it shifted in the meantime — the same idea as an HTTP ETag:
 ```abap
 METHOD data_read.
@@ -78,10 +78,10 @@ No lock is held during the edit phase, so this scales to many concurrent users a
 
 Pick a column that *always* updates on writes. If anyone writes the table bypassing `AEDAT` / `UPD_TMSTMP`, the check silently misses real conflicts.
 
-#### Combined (recommended default)
+#### 4. Combined (recommended default)
 **Lock at Save** plus the **Optimistic Check** is the safest stateless pattern and the sensible production default — the enqueue serializes parallel saves of *this* app, the timestamp check catches everyone else. See sample `Z2UI5_CL_DEMO_APP_S_10`.
 
-#### Stateful Session
+#### 5. Stateful Session
 For classic SAP GUI-like behaviour, switch the session to stateful and call the lock function module on init. The lock survives subsequent roundtrips as long as the session stays alive:
 ```abap
 IF client->check_on_init( ).
@@ -123,7 +123,7 @@ See samples `Z2UI5_CL_DEMO_APP_S_11` and `Z2UI5_CL_DEMO_APP_350` for complete ex
 Each active user pins a work process. Use stateful sessions only for low-traffic, internal apps. Always pair `set_session_stateful( )` with an explicit `set_session_stateful( abap_false )` on every exit path — otherwise a leaked enqueue blocks future users until the session times out.
 :::
 
-#### Soft Lock
+#### 6. Soft Lock
 A soft lock is a row in a custom Z table marking *"user X is editing object Y"*. It is **not** enforced by the SAP kernel — only your app code respects it — so use it for UX feedback ("locked by Alice since 09:32") and always layer it on top of a real save-time guard. A minimal schema:
 
 | Field      | Type        | Description           |
@@ -135,26 +135,29 @@ A soft lock is a row in a custom Z table marking *"user X is editing object Y"*.
 
 A user closing the browser without pressing *Release* leaves the row behind, so add a cleanup job that deletes entries older than, say, 30 minutes. See sample `Z2UI5_CL_DEMO_APP_S_12` (with the matching `Z2UI5_SAMPLE_01` table).
 
-#### RAP Drafts
+#### 7. RAP Drafts
 On modern releases, RAP draft-enabled business objects manage locking for you: the draft holds an exclusive lock for its owner while the user keeps editing — no stateful session, no `ENQUEUE_*` call. If a released SAP BO already covers your object, this is usually the simplest path. See [Draft Handling](./draft.md).
 
-#### Lock-Manager Add-on
+#### 8. Lock-Manager Add-on
 The community add-on [**lock-manager**](https://github.com/abap2UI5-addons/lock-manager) wraps the lock logic in a reusable class — including stale-lock cleanup and a "locked by X since…" message for the user. Install it like any other [add-on](../../resources/addons.md) and call it instead of writing the boilerplate yourself.
 
-#### Choosing a Strategy
-```
-Does the app edit data at all?
-├── No → render as read-only
-└── Yes
-    ├── A released, draft-enabled SAP BO already covers this object?
-    │   └── RAP Drafts
-    ├── Need "locked by X" feedback at open?
-    │   ├── Few users, GUI-like feel → Stateful Session
-    │   └── Many users               → Soft Lock + save guard
-    ├── A lock-manager add-on available for your platform?
-    │   └── Lock-Manager Add-on
-    └── Default high-scale stateless editing
-        └── Combined (Lock at Save + Optimistic Check)
-```
+#### Overview
+
+| # | Strategy | "Locked by X" while editing | Catches external writes | Stateless | Best fit |
+|---|---|---|---|---|---|
+| 1 | No Locking | no | no | yes | Demos, sandboxes |
+| 2 | Lock at Save | no | partial (race window) | yes | Single-app writers, low contention |
+| 3 | Optimistic Check | no | yes (timestamp) | yes | Many concurrent users |
+| 4 | Combined | no | yes | yes | **Production default** |
+| 5 | Stateful Session | yes (enqueue) | yes | no (pins work process) | GUI-like feel, few users |
+| 6 | Soft Lock | yes (Z table) | only via underlying guard | yes | "Locked by Alice" UX |
+| 7 | RAP Drafts | yes (RAP-managed) | yes | yes | A released draft-enabled BO exists |
+| 8 | Lock-Manager Add-on | yes | yes | yes | Skip the boilerplate |
+
+Start with **(4) Combined** unless one of these tips the balance:
+- The app is read-only → no lock needed
+- A released, draft-enabled SAP BO already covers your object → **(7) RAP Drafts**
+- You need a "locked by X since…" message at open → add **(6) Soft Lock** on top of (4), or use **(5) Stateful Session** for few users with a GUI-like feel
+- A lock-manager add-on exists for your platform → **(8) Lock-Manager Add-on**
 
 For the underlying concepts and trade-offs of statefulness, see [Statefulness](./statefulness.md).