Kontakt

Ansicht
Dokumentation

ABENRAP_HANDLER_METHODS_ABEXA - RAP HANDLER METHODS ABEXA

ABENRAP_HANDLER_METHODS_ABEXA - RAP HANDLER METHODS ABEXA

General Material Data   ABAP Short Reference  
This documentation is copyright by SAP AG.
SAP E-Book

Example for RAP Handler Methods

This example demonstrates various RAP handler methods with an unmanaged and draft-enabled RAP BO.

Note that the simplified example does not represent a real business scenario. The focus is on the technical side by giving an idea on self-implementing the handler methods of an ABAP behavior pool (ABP) and dealing with the method parameters. The code should not be reused in a production scenario.

Data Model

The CDS data model consists of the root entity DEMO_UNMANAGED_ROOT_DRAFT and its child entity DEMO_UNMANAGED_CHILD_DRAFT.

Root entity:

Child entity:

Behavior Definition

The CDS behavior definition DEMO_UNMANAGED_ROOT_DRAFT is defined in CDS BDL as follows:

The behavior definition is the basis of the implementation. It defines what can be implemented in the behavior pool.

Behavior Implementation

For the above CDS behavior definition, one ABP is created. The global class of the behavior pool is BP_DEMO_UNMANAGED_ROOT_DRAFT. The actual behavior implementation takes place in local classes that are defined and implemented in the BP_DEMO_UNMANAGED_ROOT_DRAFT==CCIMP of the behavior pool:

  • lcl_buffer constitutes the transactional buffer. It includes internal tables to handle the data.
  • lhc_demo_unmanaged_root_draft is the handler class of the behavior pool.
  • lsc_demo_unmanaged_root_draft is the saver class of the behavior pool.

Handler and saver class for the child entity are not relevant in the example.

Details of the ABP

Transactional buffer

Class / Method Details
Local class lcl_buffer In this local class, two internal tables are constructed that serve as transactional buffer: root_buffer as the transactional buffer for the root entity, and child_buffer for the child entity to also cover the create- and read-by-association operations. \lbr \lbr The underlying structured data types are built in a way that simplifies the handling of the buffers. gty_buffer, as the structured data type for root_buffer, contains all the key and data fields of the root entity's underlying CDS view with the same type. Plus, the structure includes the components cid to hold the content ID that might be provided by an instance and, for a more comfortable processing of saving and deleting instances, it includes two fields (changed and deleted) acting as flags. These flags are set in the course of modify operations, i. e. if an instance is created or changed, the changed receives an X. If an instance gets deleted, deleted gets the flag X. If no operation takes place for an entity, both fields remain initial. Likewise, the structured data type for the child entity (gty_buffer_child) is constructed. It also contains all the key and data fields of the child entity's underlying CDS view with the same type (which is in this example very similar to the root entity). This structure contains the components cid_ref for by-association operations and cid_target for the content ID of child instances in the %target structure. The latter is not used in the example. Furthermore, the component created is included. Its purpose is the same as changed, however, in this case, it is only relevant to cover create-by-association operations. Only those instances whose created field is marked with an X should be saved to the database table of the child entity.
Methods prep_root_buffer and prep_child_buffer These two methods are meant to prepare the transactional buffers for the root and child entity and fill them with data from the underlying database table, especially if the buffer tables are cleared once the save sequence gets triggered by a COMMIT ENTITIES statement in the ABAP program. \lbr The principle of internal tables as transactional buffer is the following: Once an EML call requests data (to be read or modified) with a specific key, it is checked whether the transactional buffer already holds the requested data, otherwise it is checked if the data is available in the persistent database table. If it exists there, the line with the specified key is read from the database table into the transactional buffer using a SELECT statement. The following is done in the individual methods for the operations to avoid double entries: If the data does not exist at all (for example, it got deleted), the FAILED and REPORTED structures should be filled with information about which data sets could not be read or modified. The prep_child_buffer method is relevant for the by-association operations. Not only must the availability of the line with the specified key in the root buffer be checked but also the availability of the line in the child buffer. If the line exists in the underlying database table of the child entity, the data gets read into the child buffer using a SELECT statement as well.

Handler methods

  • In each method, the name of the method is added to an internal table in the global class. This internal table is displayed in the output several times to log and visualize the sequence of the RAP handler method calls.
  • The method definitions include the explicit specification of the changing parameters in most cases.
  • In most of the method implementations, the failed and reported parameters are filled.

Method Details
create After preparing the root buffer with the provided input parameters (entities), a LOOP AT statement processes the transactional buffer further with the individual instances that come in as input parameters. There are certain conditions to be met before an instance can actually be created. If the conditions are not met for a particular instance, the result is an entry in the FAILED and REPORTED structures for the failed instance. The gist is that those instances being present in the transactional buffer and meeting the conditions receive a flag in the changed field and can finally be created. Consequently, the instances are saved to the database table following a COMMIT ENTITIES statement in the ABAP program triggering the save sequence. The checks also take the significance of the flags in the %control structure into consideration, i. e. if a data field is unmarked using the constant mk-off of interface ABP_BEHV_FLAG, this particular field should not be created with the provided value.
update Same as the method above, after preparing the root buffer with the provided input parameters (entities), a LOOP AT statement further processes the transactional buffer with the individual instances that come in as input parameters. Also here, there are certain conditions to be met before an instance can be updated. If the conditions are not met for a particular instance, an entry gets created in the FAILED and REPORTED structures for the failed instance. The checks are implemented in the way that existing values of a data field should not be overwritten if it is explicitly unmarked in the %control structure. Same as above, a changed instance receives a flag. Furthermore, the IF statements are implemented for two scenarios. It might so happen that an EML request includes only the keys or only %cid_ref. In the latter case, a potentially provided key is ignored since the reference to a particular %cid is the principal reference.
delete This method is implemented similarly to the update method, for example, it considers the two scenarios when only the key or only %cid_ref are provided. If an instance is to be deleted, it receives a flag for the deleted field. The changed field gets initialized. %control is not applicable here.
read After preparing the root buffer with the provided input parameters (keys), a LOOP AT statement is responsible for a detailed preparation and filling of the read result table according to the keys that come in as input parameters and considering the flags for the fields in the %control structure. If a data field is unmarked, this particular field should not be read and included in the read result. The key must always be read and returned.
rba_child As an initial step in the method for read-by association operations, both root and child buffers must be prepared. Same as in the read method, the LOOP AT statement is responsible for a detailed preparation and filling of the read result table according to the keys that come in as input parameters and considering the flags for the fields in the %control structure. If a data field is unmarked, this particular field should not be read and included in the read result. The key must always be read and returned.
cba_child As an initial step in the method for create-by association operations, both root and child buffers must be prepared. The conditions for filling the child buffer within the LOOP AT statement include checks for two scenarios. It might so happen that an EML request includes only the keys or only %cid_ref. In the latter case, a potentially provided key is ignored since the reference to a particular %cid is the principal reference. The flags in the %control structure for the data fields are considered, too. If the conditions are met for an instance to be created in the child entity, the instance receives a flag for the created field.
action1 Updates the string in field field2 for all requested instances. \lbr CDS BDL information: action.
action2 Action specified with result in the BDEF. Updates the string in field field1 for all requested instances. Additionally, the action's result parameter is filled. \lbr CDS BDL information: action.
action3 Action specified with parameter and result selective in the BDEF. In this example, the input parameter represents a discount percentage and the action subtracts the discount from the value of the fields field3 and field4 of an entity instance. Additionally, the action's result parameter is filled with the values of requested fields. \lbr CDS BDL information: action.
action4 Creates instances based on keys specified by the RAP consumer. Since action4 is specified with precheck in the BDEF, the method precheck_action4 is called beforehand to check the uniqueness of the keys. \lbr CDS BDL information: action, precheck.
precheck_action4 Checks that the primary keys for newly created entity instances with action4 are unique. Since action4 is specified with precheck in the BDEF, the method precheck_action4 is called before action4. In this example, the uniqueness check is actually implemented in the create method. Here, it is available for demonstration purposes and so as not to have the precheck interfere with other operations, for example, if the notation create was specified with precheck in the BDEF. \lbr CDS BDL information: precheck.
function1 Static function that applies to the complete BO, not to any specific entity instance. The function first filters all entity instances. The value of field3 should be higher than 100. Then, it sums up the values of the field field3. The value of the sum is returned in the result parameter. \lbr CDS BDL information: function.
function2 Instance function specified with parameter in the BDEF. To execute the function, it is required to specify an entity instance and also a value for the input parameter. In this example, the input parameter represents a discount percentage and the function subtracts the discount from the value of the field field3 of an entity instance. The reduced value is returned in the result parameter. \lbr CDS BDL information: function.
function3 Instance function specified with result selective in the BDEF. The importing parameter requested_fields is considered. Only those fields that are requested by the RAP consumer are filled. \lbr CDS BDL information: function.
get_instance_authorizations Checks authorization against the persistent state of the instance. The method returns information on whether update and delete operations as well as the execution of actions are allowed on instances. In this example, they are not allowed if field2 has a particular value. \lbr CDS BDL information: authorization.
lock A lock object (ELOCKRAP) is available for the database table. The method locks the active instances based on the keys (key_field). To visualize the locking, the global lock table (transaction SM12) can be checked while debugging the program. The locks are removed after the COMMIT ENTITIES statement has been executed. With regards to editing draft instances, the locks are removed after the draft action activate has been completed. \lbr CDS BDL information: locking.
get_instance_features The method returns information on whether a certain field (field3) is read-only or can be modified based on a certain condition. \lbr CDS BDL information: feature control.
get_global_features The method returns information on whether update and delete operations on instances are allowed or not based on a certain condition. \lbr CDS BDL information: feature control.
get_global_authorizations The method is implemented in a way that modify operations are only enabled for users with the appropriate authorizations. In the interest of having a simple demo, the example goes without an authorization object which is, for example, a way to handle the authorization granting in production applications. The variable auth_flag represents the authorization that is granted or not. In this example, the permission is always granted. \lbr CDS BDL information: authorization.
det_on_modify Adds a string to the existing string value in field field1. \lbr CDS BDL information: determination.
det_on_save Performs a simple calculation on the value in field field4. \lbr CDS BDL information: determination.
validation Checks if the value of field field3 is higher than 1000. \lbr CDS BDL information: validation.
activate Performs a simple calculation on the value in field field3. \lbr CDS BDL information: draft action.
discard Removes underscores from the string in field field1. \lbr CDS BDL information: draft action.
edit Converts the string in field field1 to upper case. \lbr CDS BDL information: draft action.
resume Does not contain any implementations on draft instances. It is currently not possible to call and debug this method in the demonstration program. \lbr CDS BDL information: draft action.
earlynumbering_create Early numbering is applied to primary keys. In the example, the key should be a random number between 50 and 100. The keys are mapped to %cid. \lbr CDS BDL information: early numbering.

Source Code

Execute

Description

Access with ABAP using EML

The above source code uses EML to access the unmanaged RAP business object from an ABAP program. The main focus of the program is to demonstrate RAP handler methods with several EML requests.

The output shows several runs of operations on RAP BOs to visualize the effect of implementations in the RAP handler methods as outlined above. For the program to display successful modify operations, it must be executed in a certain time frame (see the get_global_features method), otherwise all modify operations are disallowed.

  1. First run of standard operations on active instances using EML MODIFY
First, CREATE and CREATE BY operations create instances for the root and child entity. The same modify request includes UPDATE and DELETE operations on the newly created instances of the root entity. The mapped, failed and reported parameters are filled by the handler methods. The information that is returned by those parameters is displayed in internal tables. Among them, there are instances that purposely cannot be created, updated and deleted. A COMMIT ENTITIES statement triggers the save sequence. The outcome of the saving, i. e. the entries persisted to the database tables are displayed in internal tables, too. Another internal table is displayed - triggered by the get_handler_meth method - before the database entries showing handler method names. This internal table is considered as logging and visualizing the sequence of the RAP handler method calls in this run of EML modify operations.
  1. Second run of standard operations on active instances using EML MODIFY
The purpose of the second run with the same set of modify operations is to visualize the effect of further handler methods, for example get_instance_authorizations and get_instance_features. The example demonstrates that certain modify operations are not successful because of not meeting conditions that are set in those method implementations.
  1. Executing actions on active instances
Several actions are covered in the example. All of the actions have a different specification in the BDEF to show the variety of possible parameters for actions in the ABP, for example, some actions include result or request parameters. The pattern for the actions in the output is always the same: the response parameters are displayed in internal tables as well as the effect of the action execution by showing the database table entries in internal tables. Additionally, the handler method log table is displayed for all actions. The action result is displayed for those actions that include a result parameter. Action action4 is a special case since it is specified with precheck in the BDEF. Hence, the effect of the method precheck_action4 must be considered.
  1. READ, READ BY operations and executing functions on active instances
First, READ and READ BY operations are covered. The rba_child method includes an additional parameter (association_links). The content is displayed in an internal table, too, apart from the response information and read result. Then, several functions are covered in the example. All of the functions have a different specification in the BDEF to show the variety of possible parameters for functions in the ABP, for example, a function includes request parameters. The pattern for the functions in the output is always the same: the response parameters are displayed in internal tables as well as the effect of the functions by showing the read result. Additionally, the handler method log table is displayed for all actions. The action result is displayed for those actions that include a result parameter.
  1. Creating draft instances
First, new draft instances are created by marking the %is_draft indicator appropriately. The instances do not include a key. Instead, they include a content ID (%cid). The key assignment is done with the earlynumbering_create method. The handler method log table shows that the determination det_on_modify has been called, too. In the output, the response information is displayed before committing the created draft instances. With the COMMIT ENTITIES statement, the saving of the draft instances in the draft table is triggered. The execution of the activate method turns the draft instances into active instance, and the following COMMIT ENTITIES statement finally triggers the saving of the original draft instances to the database table. In the course of the draft action execution, the det_on_save and validation methods are called among others. The discard method is called last. The output shows four internal tables that log the state of draft and database tables: before and after the activation.
  1. Draft table before the activation: All created draft instances are available in the draft table. Simple edits, e. g. on field field1 triggered by the det_on_modify method are visible.
  2. Database table before activation: Does not show any changes to entries.
  3. Draft table after activation: Since the validation failed for one instance, it is still present in the draft table. It can be ignored in the example. Yet, it shows that the two other instances are no longer present.
  4. Database table after activation: Two of the three original draft instances have been saved to the database table. Simple edits, e. g. on field field1 triggered by the discard method are visible.
  • Updating draft instances
    • With the execution of the draft action edit, persisted instances are inserted in the draft table and locked on the database table. The locking effect can be checked while debugging in transaction SM12. As above, four internal tables are displayed in the output showing the state of draft and database table. The database table after activation shows the successful saving of instances with the simple edits triggered by the edit method.





    CL_GUI_FRONTEND_SERVICES - Frontend Services   PERFORM Short Reference  
    This documentation is copyright by SAP AG.

    Length: 28248 Date: 20240427 Time: 045713     sap01-206 ( 763 ms )