Behavior Implementations Part 1: The Behavior Pool — Handler and Saver Classes

📌 KEY POINTS
✅ Code lives in local handler classes (interaction) and the saver (save phase).
✅ Generate methods from the BDEF with Ctrl+1.
✅ failed / reported / mapped are implicit response parameters.
📌 Use %tky everywhere — it includes %is_draft.

▶ WHAT THIS SERIES COVERS
The behavior definition says what a BO can do; the behavior implementation is the ABAP code that does the non-standard parts. This series explains the mechanics; the Managed RAP series shows them in a full build.

• Part 1 — the behavior pool: handler and saver classes (this lesson)
• Part 2 — determinations and validations without side effects
• Part 3 — actions, results and user-facing messages
• Part 4 — save sequence, late numbering and unmanaged save in the saver
• Part 5 — performance, unit testing and debugging

━━━━━━━━━━━━━━━━━━━━
▶ THE BEHAVIOR POOL
The behavior pool is a global class, e.g. ZBP_R_PURCHREQ, declared "ABSTRACT FINAL FOR BEHAVIOR OF zr_purchreq". The global class itself is empty. All code lives in the local types include (the Local Types tab in ADT), in local classes:

• Handler classes — "INHERITING FROM cl_abap_behavior_handler", usually one per entity (lhc_PurchaseRequest, lhc_Item). They contain the interaction-phase methods: determinations, validations, actions, functions, authorization, feature control, prechecks, and in unmanaged BOs also CRUD, read and lock.
• Saver class — "INHERITING FROM cl_abap_behavior_saver" (lsc_…). Only needed for save-phase code: finalize, check_before_save, adjust_numbers, save / save_modified, cleanup, cleanup_finalize.

You do not create these by hand: place the cursor on the class name or a BDEF element and use the ADT quick fix (Ctrl+1).

━━━━━━━━━━━━━━━━━━━━
▶ METHOD SIGNATURES — GENERATED FROM THE BDEF
Each BDEF element produces a method with a special FOR clause:

• "METHODS setInitialStatus FOR DETERMINE ON MODIFY IMPORTING keys FOR PurchaseRequest~setInitialStatus."
• "METHODS validateDescription FOR VALIDATE ON SAVE IMPORTING keys FOR PurchaseRequest~validateDescription."
• "METHODS approve FOR MODIFY IMPORTING keys FOR ACTION PurchaseRequest~approve RESULT result."
• "METHODS get_instance_features FOR INSTANCE FEATURES IMPORTING keys REQUEST requested_features FOR PurchaseRequest RESULT result."
• "METHODS get_global_authorizations FOR GLOBAL AUTHORIZATION IMPORTING REQUEST requested_authorizations FOR PurchaseRequest RESULT result."

You never call these methods yourself; RAP calls them at the right time.

━━━━━━━━━━━━━━━━━━━━
▶ IMPLICIT PARAMETERS
Besides the declared ones, most methods have implicit changing parameters:

• failed — instances that failed (with %fail-cause).
• reported — messages per instance (%msg) or unbound (%other).
• mapped — key mapping for new instances (%cid → key), in methods that create.

Their types are derived from the BO, so you address them per entity: failed-purchaserequest, reported-item.

━━━━━━━━━━━━━━━━━━━━
▶ DERIVED TYPES
RAP generates types for everything: "TYPE TABLE FOR CREATE zr_purchreq", "TYPE TABLE FOR READ RESULT zr_purchreq", "TYPE RESPONSE FOR FAILED zr_purchreq". You rarely declare them explicitly — inline declarations (DATA(...)) and VALUE #( ) infer them.

THE %-COMPONENTS YOU MUST KNOW

• %tky — transactional key: the key plus %is_draft (if draft). Use it everywhere to identify instances.
• %key — only the key fields.
• %cid / %cid_ref — content ID of a new instance / reference to it within one request.
• %pid — preliminary ID with late numbering.
• %is_draft — draft (mk-on) or active instance.
• %control — which fields were supplied (mk-on per field).
• %param — action parameter or action result data.
• %msg — message object; %element — field(s) to highlight; %state_area — message group; %fail-cause — reason in failed.
• %other — messages not bound to an instance.

━━━━━━━━━━━━━━━━━━━━
▶ GOLDEN RULES FOR ALL HANDLER CODE

1. Every method receives a table — process all rows.
2. Read with READ ENTITIES … IN LOCAL MODE, change with MODIFY ENTITIES … IN LOCAL MODE.
3. Use %tky, not key fields.
4. No COMMIT, no direct DML on the BO's tables, no dialogs.
5. Report problems via failed and reported, never by raising unhandled exceptions or MESSAGE statements.

━━━━━━━━━━━━━━━━━━━━
▶ WHAT YOU HAVE AFTER PART 1
The map of a behavior pool. Part 2 implements determinations and validations correctly.

A team's first RAP BO grew into one 1,800-line handler class for all entities, with helper methods mixed in and several methods working on the first key only. Bugs appeared whenever Fiori sent more than one instance, for example in mass actions.
In a refactoring, they split the code into one handler per entity, moved reusable logic into a separate domain class, and applied the golden rules (process all rows, EML in local mode, %tky, failed/reported). The class became readable, the multi-instance bugs disappeared, and new team members could find the method for a BDEF element immediately.

• Putting code into the global class instead of the local types include.
• One giant handler for all entities.
• Processing only keys[ 1 ].
• Using key fields instead of %tky, breaking draft.
• Raising MESSAGE or unhandled exceptions instead of filling failed and reported.
• Writing methods by hand instead of generating them from the BDEF.

• Generate method stubs with the ADT quick fix.
• One handler class per entity; saver only when needed.
• Extract larger reusable logic into separate classes called from handlers.
• Learn the %-components; use %tky everywhere.
• Follow the golden rules in every method and check them in code reviews.

Questions: "What is a behavior pool?", "What is the difference between a handler and a saver class?", "What are failed, reported and mapped?", "What is %tky?"
Strong answer: the behavior pool is a global class FOR BEHAVIOR OF the BO with local handler classes (interaction phase: determinations, validations, actions, authorization, feature control, and CRUD in unmanaged) and an optional saver class (save sequence). Methods are generated from BDEF elements. failed, reported and mapped are implicit response parameters. %tky is the key plus %is_draft, used to identify instances in draft-enabled BOs.