docs: add Draft Handling and Locks pages under Specifics

Author: oblomov-dev

docs/.vitepress/config.mjs

@@ -159,6 +159,8 @@ export default defineConfig({
               { text: "Logging", link: "/development/specific/logging" },
               { text: "Camera", link: "/development/specific/camera" },
               { text: "CDS, EML", link: "/development/specific/cds" },
+              { text: "Draft Handling", link: "/development/specific/draft" },
+              { text: "Locks", link: "/development/specific/locks" },
               { text: "Timer", link: "/development/specific/timer" },
               { text: "Drag & Drop", link: "/development/specific/drag" },
               {

docs/development/specific/draft.md

@@ -0,0 +1,48 @@
+---
+outline: [2, 4]
+---
+# Draft Handling
+
+Draft handling lets users save unfinished work — for example, a half-filled form — without committing it to the active database state. With abap2UI5 you can drive RAP draft-enabled business objects directly through EML.
+
+### Modify a Draft
+Use `MODIFY ENTITIES` with the `IN LOCAL MODE` and the draft addition to create or update draft instances:
+```abap
+MODIFY ENTITIES OF i_salesordertp
+       ENTITY salesorder
+       CREATE
+       FIELDS ( salesordertype salesorganization )
+       WITH VALUE #( ( %cid     = `0001`
+                       %is_draft = if_abap_behv=>mk-on
+                       %data     = VALUE #(
+                           SalesOrderType    = `TA`
+                           SalesOrganization = `1010` ) ) )
+       MAPPED   DATA(ls_mapped)
+       FAILED   DATA(ls_failed)
+       REPORTED DATA(ls_reported).
+```
+
+### Activate a Draft
+Promote the draft to the active state with the `Activate` action and commit:
+```abap
+MODIFY ENTITIES OF i_salesordertp
+       ENTITY salesorder
+       EXECUTE Activate
+       FROM VALUE #( ( %key       = ls_key
+                       %is_draft  = if_abap_behv=>mk-on ) )
+       MAPPED   DATA(ls_mapped_act)
+       FAILED   DATA(ls_failed_act)
+       REPORTED DATA(ls_reported_act).
+
+COMMIT ENTITIES BEGIN
+       RESPONSE OF i_salesordertp
+       FAILED   DATA(ls_save_failed)
+       REPORTED DATA(ls_save_reported).
+COMMIT ENTITIES END.
+```
+
+For more on EML in abap2UI5 apps, see [CDS, EML](./cds.md).
+
+::: tip
+Draft tables hold exclusive locks for the draft owner. Combine draft handling with [Locks](./locks.md) only when you also need backend lock objects outside of RAP.
+:::

docs/development/specific/locks.md

@@ -0,0 +1,36 @@
+---
+outline: [2, 4]
+---
+# Locks
+
+Business logic often needs to prevent two users from editing the same object at the same time. Because abap2UI5 runs stateless by default, locks held with `ENQUEUE` / `DEQUEUE` are released at the end of each roundtrip — so locking needs a deliberate approach.
+
+### Lock with a Stateful Session
+Switch the session to stateful and call the lock function module. The lock survives subsequent roundtrips as long as the session stays stateful:
+```abap
+CALL FUNCTION `ENQUEUE_E_TABLE`
+  EXPORTING
+    tabname        = `ZTEST`
+    varkey         = varkey
+  EXCEPTIONS
+    foreign_lock   = 1
+    system_failure = 2
+    OTHERS         = 3.
+
+IF sy-subrc = 0.
+  client->set_session_stateful( ).
+ELSE.
+  client->set_session_stateful( abap_false ).
+ENDIF.
+```
+
+Release the lock by ending the stateful session — for example on navigation away from the edit view:
+```abap
+client->set_session_stateful( abap_false ).
+client->nav_app_leave( ).
+```
+
+A complete example is in sample `Z2UI5_CL_DEMO_APP_350`.
+
+### Other Options
+Stateful sessions are only available on private and on-premise systems. For other deployments, infinite backend sessions can hold locks while the UI5 app keeps talking statelessly. See [Statefulness, Locks](../../advanced/stateful.md) for the alternatives and trade-offs.