- SAP Managed Tags:
In my previous blog james.wood/blog/2013/01/04/navigating-the-bopf-part-2--business-object-overview, we explored the anatomy of business objects within the BOPF. There, we were able to observe the various entities that make up a BO: nodes/attributes, actions, associations, determinations, validations, and queries. Now that you have a feel for what these entities are, we're ready to begin taking a look at the API that is used to manipulate these entities. To guide us through this demonstration, we'll explore the construction of a simple ABAP report program used to perform CRUD operations on a sample BOPF BO shipped by default by SAP: /BOBF/DEMO_CUSTOMER. You can download the complete example program source code here.
Note: The code bundle described above has been enhanced as of 9/18/2013. The code was reworked to factor out a BOPF utilities class of sorts and also demonstrate how to traverse over to dependent objects (DOs).
BOPF API Overview
Before we begin coding with the BOPF API, let's first take a look at its basic structure. The UML class diagram below highlights some of the main classes that make up the BOPF API. At the end of the day, there are three main objects that we'll be working with to perform most of the operations within the BOPF:
/BOBF/IF_TRA_TRANSACTION_MGR- This object reference provides a transaction manager which can be used to manage transactional changes. Such transactions could contain a single step (e.g. update node X) or be strung out across multiple steps (add a node, call an action, and so on).
/BOBF/IF_TRA_SERVICE_MANAGER- The service manager object reference provides us with the methods we need to lookup BO nodes, update BO nodes, trigger validations, perform actions, and so on.
/BOBF/IF_FRW_CONFIGURATION- This object reference provides us with metadata for a particular BO. We'll explore the utility of having access to this metadata coming up shortly.
In the upcoming sections, I'll show you how these various API classes collaborate in typical BOPF use cases. Along the way, we'll encounter other useful classes that can be used to perform specific tasks. You can find a complete class listing within package /BOBF/MAIN.
Note: As you'll soon see, the BOPF API is extremely generic in nature. While this provides tremendous flexibility, it also adds a certain amount of tedium to common tasks. Thus, in many applications, you may find that SAP has elected to wrap the API up in another API that is more convenient to work with. For example, in the SAP EHSM solution, SAP defines an "Easy Node Access" API which simplfies the way that developers traverse BO nodes, perform updates, and so on.
Case Study: Building a Simple Report Program to Manipulate Customer Objects
To demonstrate the BOPF API, we'll build a custom report program which performs basic CRUD operations on a sample BO provided by SAP: /BOBF/DEMO_CUSTOMER. The figure below shows the makeup of this BO in Transaction /BOBF/CONF_UI.
Our sample program provides a basic UI as shown below. Here, users have the option of creating, changing, and displaying a particular customer using its ID number. Sort of a simplified Transaction XK01-XK03 if you will.
Getting Started
To drive the application functionality, we'll create a local test driver class called LCL_DEMO. As you can see in the code excerpt below, this test driver class loads the core BOPF API objects at setup whenever the CONSTRUCTOR method is invoked. Here, the factory classes illustrated in the UML class diagram shown in the previous section are used to load the various object references.
CLASS lcl_demo DEFINITION CREATE PRIVATE.
PRIVATE SECTION.
DATA mo_txn_mngr TYPE REF TO /bobf/if_tra_transaction_mgr.
DATA mo_svc_mngr TYPE REF TO /bobf/if_tra_service_manager.
DATA mo_bo_conf TYPE REF TO /bobf/if_frw_configuration. METHODS:
constructor RAISING /bobf/cx_frw.
ENDCLASS.
CLASS lcl_demo IMPLEMENTATION.
METHOD constructor.
"Obtain a reference to the BOPF transaction manager:
me->mo_txn_mngr =
/bobf/cl_tra_trans_mgr_factory=>get_transaction_manager( ).
"Obtain a reference to the BOPF service manager:
me->mo_svc_mngr =
/bobf/cl_tra_serv_mgr_factory=>get_service_manager(
/bobf/if_demo_customer_c=>sc_bo_key ).
"Access the metadata for the /BOBF/DEMO_CUSTOMER BO:
me->mo_bo_conf =
/bobf/cl_frw_factory=>get_configuration(
/bobf/if_demo_customer_c=>sc_bo_key ).
ENDMETHOD. " METHOD constructor
ENDCLASS.
For the most part, this should seem fairly straightforward. However, you might be wondering where I came up with the IV_BO_KEY parameter in the GET_SERVICE_MANAGER() and GET_CONFIGURATION() factory method calls. This value is provided to us via the BO's constants interface (/BOBF/IF_DEMO_CUSTOMER_C in this case) which can be found within the BO configuration in Transaction /BOBF/CONF_UI (see below). This auto-generated constants interface provides us with a convenient mechanism for addressing a BO's key, its defined nodes, associations, queries, and so on. We'll end up using this interface quite a bit during the course of our development.
Creating New Customers
Once we have the basic framework in place, we are ready to commence with the development of the various CRUD operations that our application will support. To get things started, we'll take a look at the creation of a new customer instance. For the most part, this involves little more than a call to the MODIFY() method of the /BOBF/IF_TRA_SERVICE_MANAGER object reference. Of course, as you can see in the code excerpt below, there is a fair amount of setup that we must do before we can call this method.
CLASS lcl_demo DEFINITION CREATE PRIVATE.
PUBLIC SECTION.
CLASS-METHODS:
create_customer IMPORTING iv_customer_id
TYPE /bobf/demo_customer_id.
...
ENDCLASS.CLASS lcl_demo IMPLEMENTATION.
METHOD create_customer.
"Method-Local Data Declarations:
DATA lo_driver TYPE REF TO lcl_demo.
DATA lt_mod TYPE /bobf/t_frw_modification.
DATA lo_change TYPE REF TO /bobf/if_tra_change.
DATA lo_message TYPE REF TO /bobf/if_frw_message.
DATA lv_rejected TYPE boole_d.
DATA lx_bopf_ex TYPE REF TO /bobf/cx_frw.
DATA lv_err_msg TYPE string.
DATA lr_s_root TYPE REF TO /bobf/s_demo_customer_hdr_k.
DATA lr_s_txt TYPE REF TO /bobf/s_demo_short_text_k.
DATA lr_s_txt_hdr TYPE REF TO /bobf/s_demo_longtext_hdr_k.
DATA lr_s_txt_cont TYPE REF TO /bobf/s_demo_longtext_item_k.
FIELD-SYMBOLS:
<ls_mod> LIKE LINE OF lt_mod.
"Use the BOPF API to create a new customer record:
TRY.
"Instantiate the driver class:
CREATE OBJECT lo_driver.
"Build the ROOT node:
CREATE DATA lr_s_root.
lr_s_root->key = /bobf/cl_frw_factory=>get_new_key( ).
lr_s_root->customer_id = iv_customer_id.
lr_s_root->sales_org = 'AMER'.
lr_s_root->cust_curr = 'USD'.
lr_s_root->address_contry = 'US'.
lr_s_root->address = '1234 Any Street'.
APPEND INITIAL LINE TO lt_mod ASSIGNING <ls_mod>.
<ls_mod>-node = /bobf/if_demo_customer_c=>sc_node-root.
<ls_mod>-change_mode = /bobf/if_frw_c=>sc_modify_create.
<ls_mod>-key = lr_s_root->key.
<ls_mod>-data = lr_s_root.
"Build the ROOT_TEXT node:
CREATE DATA lr_s_txt.
lr_s_txt->key = /bobf/cl_frw_factory=>get_new_key( ).
lr_s_txt->text = 'Sample Customer Record'.
lr_s_txt->language = sy-langu.
APPEND INITIAL LINE TO lt_mod ASSIGNING <ls_mod>.
<ls_mod>-node = /bobf/if_demo_customer_c=>sc_node-root_text.
<ls_mod>-change_mode = /bobf/if_frw_c=>sc_modify_create.
<ls_mod>-source_node = /bobf/if_demo_customer_c=>sc_node-root.
<ls_mod>-association =
/bobf/if_demo_customer_c=>sc_association-root-root_text.
<ls_mod>-source_key = lr_s_root->key.
<ls_mod>-key = lr_s_txt->key.
<ls_mod>-data = lr_s_txt.
"Build the ROOT_LONG_TEXT node:
"If you look at the node type for this node, you'll notice that
"it's a "Delegated Node". In other words, it is defined in terms
"of the /BOBF/DEMO_TEXT_COLLECTION business object. The following
"code accounts for this indirection.
CREATE DATA lr_s_txt_hdr.
lr_s_txt_hdr->key = /bobf/cl_frw_factory=>get_new_key( ).
APPEND INITIAL LINE TO lt_mod ASSIGNING <ls_mod>.
<ls_mod>-node = /bobf/if_demo_customer_c=>sc_node-root_long_text.
<ls_mod>-change_mode = /bobf/if_frw_c=>sc_modify_create.
<ls_mod>-source_node = /bobf/if_demo_customer_c=>sc_node-root.
<ls_mod>-association =
/bobf/if_demo_customer_c=>sc_association-root-root_long_text.
<ls_mod>-source_key = lr_s_root->key.
<ls_mod>-key = lr_s_txt_hdr->key.
<ls_mod>-data = lr_s_txt_hdr.
"Create the CONTENT node:
CREATE DATA lr_s_txt_cont.
lr_s_txt_cont->key = /bobf/cl_frw_factory=>get_new_key( ).
lr_s_txt_cont->language = sy-langu.
lr_s_txt_cont->text_type = 'MEMO'.
lr_s_txt_cont->text_content = 'Demo customer created via BOPF API.'.
APPEND INITIAL LINE TO lt_mod ASSIGNING <ls_mod>.
<ls_mod>-node =
lo_driver->mo_bo_conf->query_node(
iv_proxy_node_name = 'ROOT_LONG_TXT.CONTENT' ).
<ls_mod>-change_mode = /bobf/if_frw_c=>sc_modify_create.
<ls_mod>-source_node = /bobf/if_demo_customer_c=>sc_node-root_long_text.
<ls_mod>-source_key = lr_s_txt_hdr->key.
<ls_mod>-key = lr_s_txt_cont->key.
<ls_mod>-data = lr_s_txt_cont.
<ls_mod>-association =
lo_driver->mo_bo_conf->query_assoc(
iv_node_key = /bobf/if_demo_customer_c=>sc_node-root_long_text
iv_assoc_name = 'CONTENT' ).
"Create the customer record:
CALL METHOD lo_driver->mo_svc_mngr->modify
EXPORTING
it_modification = lt_mod
IMPORTING
eo_change = lo_change
eo_message = lo_message.
"Check for errors:
IF lo_message IS BOUND.
IF lo_message->check( ) EQ abap_true.
lo_driver->display_messages( lo_message ).
RETURN.
ENDIF.
ENDIF.
"Apply the transactional changes:
CALL METHOD lo_driver->mo_txn_mngr->save
IMPORTING
eo_message = lo_message
ev_rejected = lv_rejected.
IF lv_rejected EQ abap_true.
lo_driver->display_messages( lo_message ).
RETURN.
ENDIF.
"If we get to here, then the operation was successful:
WRITE: / 'Customer', iv_customer_id, 'created successfully.'.
CATCH /bobf/cx_frw INTO lx_bopf_ex.
lv_err_msg = lx_bopf_ex->get_text( ).
WRITE: / lv_err_msg.
ENDTRY.
ENDMETHOD. " METHOD create_customer
ENDCLASS.
As you can see in the code excerpt above, the majority of the code is devoted to building a table which is passed in the IT_MODIFICATION parameter of the MODIFY() method. Here, a separate record is created for each node row that is being modified (or inserted in this case). This record contains information such as the node object key (NODE), the edit mode (CHANGE_MODE), the row key (KEY) which is an auto-generated GUID, association/parent key information, and of course, the actual data (DATA). If you've ever worked with ALE IDocs, then this will probably feel vaguely familiar.
Looking more closely at the population of the node row data, you can see that we're working with data references which are created dynamically using the CREATE DATA statement. This indirection is necessary since the BOPF API is generic in nature. You can find the structure definitions for each node by double-clicking on the node in Transaction /BOBF/CONF_UI and looking at the Combined Structure field (see below).
Once the modification table is filled out, we can call the MODIFY() method to insert the record(s). Assuming all is successful, we can then commit the transaction by calling the SAVE() method on the /BOBF/IF_TRA_TRANSACTION_MANAGER instance. Should any errors occur, we can display the error messages using methods of the /BOBF/IF_FRW_MESSAGE object reference which is returned from both methods. This is evidenced by the simple utility method DISPLAY_MESSAGES() shown below. That's pretty much all there is to it.
CLASS lcl_demo DEFINITION CREATE PRIVATE.
PRIVATE SECTION.
METHODS:
display_messages IMPORTING io_message
TYPE REF TO /bobf/if_frw_message.
ENDCLASS.CLASS lcl_demo IMPLEMENTATION.
METHOD display_messages.
"Method-Local Data Declarations:
DATA lt_messages TYPE /bobf/t_frw_message_k.
DATA lv_msg_text TYPE string.
FIELD-SYMBOLS <ls_message> LIKE LINE OF lt_messages.
"Sanity check:
CHECK io_message IS BOUND.
"Output each of the messages in the collection:
io_message->get_messages( IMPORTING et_message = lt_messages ).
LOOP AT lt_messages ASSIGNING <ls_message>.
lv_msg_text = <ls_message>-message->get_text( ).
WRITE: / lv_msg_text.
ENDLOOP.
ENDMETHOD. " METHOD display_messages
ENDCLASS.
Performing Customer Queries
If you look closely at the customer creation code illustrated in the previous section, you can see that each node row is keyed by an auto-generated GUID of type /BOBF/CONF_KEY (see below). Since most users don't happen to have 32-character hex strings memorized, we typically have to resort to queries if we want to find particular BO instances. For example, in our customer demo program, we want to provide a way for users to lookup customers using their customer ID value. Of course, we could have just as easily defined an alternative query selection to pull the customer records.
As we learned in the previous blog post, most BOs come with one or more queries which allow us to search for BOs according to various node criteria. In the case of the /BOBF/DEMO_CUSTOMER business object, we want to use the SELECT_BY_ATTRIBUTES query attached to the ROOT node (see below). This allows us to lookup customers by their ID value.
The code excerpt below shows how we defined our query in a method called GET_CUSTOMER_FOR_ID(). As you can see, the query is executed by calling the aptly named QUERY() method of the /BOBF/IF_TRA_SERVICE_MANAGER instance. The query parameters are provided in the form of an internal table of type /BOBF/T_FRW_QUERY_SELPARAM. This table type has a similar look and feel to a range table or SELECT-OPTION. The results of the query are returned in a table of type /BOBF/T_FRW_KEY. This table contains the keys of the node rows that matched the query parameters. In our sample case, there should be only one match, so we simply return the first key in the list.
CLASS lcl_demo DEFINITION CREATE PRIVATE.
PRIVATE SECTION.
METHODS:
get_customer_for_id IMPORTING iv_customer_id
TYPE /bobf/demo_customer_id
RETURNING VALUE(rv_customer_key)
TYPE /bobf/conf_key
RAISING /bobf/cx_frw.
ENDCLASS.CLASS lcl_demo IMPLEMENTATION.
METHOD get_customer_for_id.
"Method-Local Data Declarations:
DATA lo_driver TYPE REF TO lcl_demo.
DATA lt_parameters TYPE /bobf/t_frw_query_selparam.
DATA lt_customer_keys TYPE /bobf/t_frw_key.
DATA lx_bopf_ex TYPE REF TO /bobf/cx_frw.
DATA lv_err_msg TYPE string.
FIELD-SYMBOLS <ls_parameter> LIKE LINE OF lt_parameters.
FIELD-SYMBOLS <ls_customer_key> LIKE LINE OF lt_customer_keys.
"Instantiate the test driver class:
CREATE OBJECT lo_driver.
"Though we could conceivably lookup the customer using an SQL query,
"the preferred method of selection is a BOPF query:
APPEND INITIAL LINE TO lt_parameters ASSIGNING <ls_parameter>.
<ls_parameter>-attribute_name =
/bobf/if_demo_customer_c=>sc_query_attribute-root-select_by_attributes-customer_id.
<ls_parameter>-sign = 'I'.
<ls_parameter>-option = 'EQ'.
<ls_parameter>-low = iv_customer_id.
CALL METHOD lo_driver->mo_svc_mngr->query
EXPORTING
iv_query_key =
/bobf/if_demo_customer_c=>sc_query-root-select_by_attributes
it_selection_parameters = lt_parameters
IMPORTING
et_key = lt_customer_keys.
"Return the matching customer's KEY value:
READ TABLE lt_customer_keys INDEX 1 ASSIGNING <ls_customer_key>.
IF sy-subrc EQ 0.
rv_customer_key = <ls_customer_key>-key.
ENDIF.
ENDMETHOD. " METHOD get_customer_for_id
ENDCLASS.
Displaying Customer Records
With the query logic now in place, we now know which customer record to lookup. The question is, how do we retrieve it? For this task, we must use the
RETRIEVE() and RETRIEVE_BY_ASSOCIATION() methods provided by the /BOBF/IF_TRA_SERVICE_MANAGER instance. As simple as this sounds, the devil is in the details. Here, in addition to constructing the calls to the RETRIEVE*() methods, we must also dynamically define the result tables which will be used to store the results.
As you can see in the code excerpt below, we begin our search by accessing the customer ROOT node using the RETRIEVE() method. Here, the heavy lifting is performed by the GET_NODE_ROW() and GET_NODE_TABLE() helper methods. Looking at the implementation of the GET_NODE_TABLE() method, you can see how we're using the /BOBF/IF_FRW_CONFIGURATION object reference to lookup the node's metadata. This metadata provides us with the information we need to construct an internal table to house the results returned from the RETRIEVE() method. The GET_NODE_ROW() method then dynamically retrieves the record located at the index defined by the IV_INDEX parameter.
Within the DISPLAY_CUSTOMER() method, we get our hands on the results by performing a cast on the returned structure reference. From here, we can access the row attributes as per usual.
After the root node has been retrieved, we can traverse to the child nodes of the /BOBF/DEMO_CUSTOMER object using the RETRIEVE_BY_ASSOCIATION() method. Here, the process is basically the same. The primary difference is in the way we lookup the association metadata which is used to build the call to RETRIEVE_BY_ASSOCIATION(). Once again, we perform a cast on the returned structure reference and display the sub-node attributes from there.
CLASS lcl_demo DEFINITION CREATE PRIVATE.
PUBLIC SECTION.
CLASS-METHODS:
display_customer IMPORTING iv_customer_id
TYPE /bobf/demo_customer_id. PRIVATE SECTION.
METHODS:
get_node_table IMPORTING iv_key TYPE /bobf/conf_key
iv_node_key TYPE /bobf/obm_node_key
iv_edit_mode TYPE /bobf/conf_edit_mode
DEFAULT /bobf/if_conf_c=>sc_edit_read_only
RETURNING VALUE(rr_data) TYPE REF TO data
RAISING /bobf/cx_frw,
get_node_row IMPORTING iv_key TYPE /bobf/conf_key
iv_node_key TYPE /bobf/obm_node_key
iv_edit_mode TYPE /bobf/conf_edit_mode
DEFAULT /bobf/if_conf_c=>sc_edit_read_only
iv_index TYPE i DEFAULT 1
RETURNING VALUE(rr_data) TYPE REF TO data
RAISING /bobf/cx_frw,
get_node_table_by_assoc IMPORTING iv_key TYPE /bobf/conf_key
iv_node_key TYPE /bobf/obm_node_key
iv_assoc_key TYPE /bobf/obm_assoc_key
iv_edit_mode TYPE /bobf/conf_edit_mode
DEFAULT /bobf/if_conf_c=>sc_edit_read_only
RETURNING VALUE(rr_data) TYPE REF TO data
RAISING /bobf/cx_frw,
get_node_row_by_assoc IMPORTING iv_key TYPE /bobf/conf_key
iv_node_key TYPE /bobf/obm_node_key
iv_assoc_key TYPE /bobf/obm_assoc_key
iv_edit_mode TYPE /bobf/conf_edit_mode
DEFAULT /bobf/if_conf_c=>sc_edit_read_only
iv_index TYPE i DEFAULT 1
RETURNING VALUE(rr_data) TYPE REF TO data
RAISING /bobf/cx_frw.
ENDCLASS.
CLASS lcl_demo IMPLEMENTATION.
METHOD display_customer.
"Method-Local Data Declarations:
DATA lo_driver TYPE REF TO lcl_demo.
DATA lv_customer_key TYPE /bobf/conf_key.
DATA lx_bopf_ex TYPE REF TO /bobf/cx_frw.
DATA lv_err_msg TYPE string.
DATA lr_s_root TYPE REF TO /bobf/s_demo_customer_hdr_k.
DATA lr_s_text TYPE REF TO /bobf/s_demo_short_text_k.
"Try to display the selected customer:
TRY.
"Instantiate the test driver class:
CREATE OBJECT lo_driver.
"Lookup the customer's key attribute using a query:
lv_customer_key = lo_driver->get_customer_for_id( iv_customer_id ).
"Display the header-level details for the customer:
lr_s_root ?=
lo_driver->get_node_row(
iv_key = lv_customer_key
iv_node_key = /bobf/if_demo_customer_c=>sc_node-root
iv_index = 1 ).
WRITE: / 'Display Customer', lr_s_root->customer_id.
ULINE.
WRITE: / 'Sales Organization:', lr_s_root->sales_org.
WRITE: / 'Address:', lr_s_root->address.
SKIP.
"Traverse to the ROOT_TEXT node to display the customer short text:
lr_s_text ?=
lo_driver->get_node_row_by_assoc(
iv_key = lv_customer_key
iv_node_key = /bobf/if_demo_customer_c=>sc_node-root
iv_assoc_key = /bobf/if_demo_customer_c=>sc_association-root-root_text
iv_index = 1 ).
WRITE: / 'Short Text:', lr_s_text->text.
CATCH /bobf/cx_frw INTO lx_bopf_ex.
lv_err_msg = lx_bopf_ex->get_text( ).
WRITE: / lv_err_msg.
ENDTRY.
ENDMETHOD. " METHOD display_customer
METHOD get_node_table.
"Method-Local Data Declarations:
DATA lt_key TYPE /bobf/t_frw_key.
DATA ls_node_conf TYPE /bobf/s_confro_node.
DATA lo_change TYPE REF TO /bobf/if_tra_change.
DATA lo_message TYPE REF TO /bobf/if_frw_message.
FIELD-SYMBOLS <ls_key> LIKE LINE OF lt_key.
FIELD-SYMBOLS <lt_data> TYPE INDEX TABLE.
"Lookup the node's configuration:
CALL METHOD mo_bo_conf->get_node
EXPORTING
iv_node_key = iv_node_key
IMPORTING
es_node = ls_node_conf.
"Use the node configuration metadata to create the result table:
CREATE DATA rr_data TYPE (ls_node_conf-data_table_type).
ASSIGN rr_data->* TO <lt_data>.
"Retrieve the target node:
APPEND INITIAL LINE TO lt_key ASSIGNING <ls_key>.
<ls_key>-key = iv_key.
CALL METHOD mo_svc_mngr->retrieve
EXPORTING
iv_node_key = iv_node_key
it_key = lt_key
IMPORTING
eo_message = lo_message
eo_change = lo_change
et_data = <lt_data>.
"Check the results:
IF lo_message IS BOUND.
IF lo_message->check( ) EQ abap_true.
display_messages( lo_message ).
RAISE EXCEPTION TYPE /bobf/cx_dac.
ENDIF.
ENDIF.
ENDMETHOD. " METHOD get_node_table
METHOD get_node_row.
"Method-Local Data Declarations:
DATA lr_t_data TYPE REF TO data.
FIELD-SYMBOLS <lt_data> TYPE INDEX TABLE.
FIELD-SYMBOLS <ls_row> TYPE ANY.
"Lookup the node data:
lr_t_data =
get_node_table( iv_key = iv_key
iv_node_key = iv_node_key
iv_edit_mode = iv_edit_mode ).
IF lr_t_data IS NOT BOUND.
RAISE EXCEPTION TYPE /bobf/cx_dac.
ENDIF.
"Try to pull the record at the specified index:
ASSIGN lr_t_data->* TO <lt_data>.
READ TABLE <lt_data> INDEX iv_index ASSIGNING <ls_row>.
IF sy-subrc EQ 0.
GET REFERENCE OF <ls_row> INTO rr_data.
ELSE.
RAISE EXCEPTION TYPE /bobf/cx_dac.
ENDIF.
ENDMETHOD. " METHOD get_node_row
METHOD get_node_table_by_assoc.
"Method-Local Data Declarations:
DATA lt_key TYPE /bobf/t_frw_key.
DATA ls_node_conf TYPE /bobf/s_confro_node.
DATA ls_association TYPE /bobf/s_confro_assoc.
DATA lo_change TYPE REF TO /bobf/if_tra_change.
DATA lo_message TYPE REF TO /bobf/if_frw_message.
FIELD-SYMBOLS <ls_key> LIKE LINE OF lt_key.
FIELD-SYMBOLS <lt_data> TYPE INDEX TABLE.
"Lookup the association metadata to find out more
"information about the target sub-node:
CALL METHOD mo_bo_conf->get_assoc
EXPORTING
iv_assoc_key = iv_assoc_key
iv_node_key = iv_node_key
IMPORTING
es_assoc = ls_association.
IF ls_association-target_node IS NOT BOUND.
RAISE EXCEPTION TYPE /bobf/cx_dac.
ENDIF.
"Use the node configuration metadata to create the result table:
ls_node_conf = ls_association-target_node->*.
CREATE DATA rr_data TYPE (ls_node_conf-data_table_type).
ASSIGN rr_data->* TO <lt_data>.
"Retrieve the target node:
APPEND INITIAL LINE TO lt_key ASSIGNING <ls_key>.
<ls_key>-key = iv_key.
CALL METHOD mo_svc_mngr->retrieve_by_association
EXPORTING
iv_node_key = iv_node_key
it_key = lt_key
iv_association = iv_assoc_key
iv_fill_data = abap_true
IMPORTING
eo_message = lo_message
eo_change = lo_change
et_data = <lt_data>.
"Check the results:
IF lo_message IS BOUND.
IF lo_message->check( ) EQ abap_true.
display_messages( lo_message ).
RAISE EXCEPTION TYPE /bobf/cx_dac.
ENDIF.
ENDIF.
ENDMETHOD. " METHOD get_node_table_by_assoc
METHOD get_node_row_by_assoc.
"Method-Local Data Declarations:
DATA lr_t_data TYPE REF TO data.
FIELD-SYMBOLS <lt_data> TYPE INDEX TABLE.
FIELD-SYMBOLS <ls_row> TYPE ANY.
"Lookup the node data:
lr_t_data =
get_node_table_by_assoc( iv_key = iv_key
iv_node_key = iv_node_key
iv_assoc_key = iv_assoc_key
iv_edit_mode = iv_edit_mode ).
IF lr_t_data IS NOT BOUND.
RAISE EXCEPTION TYPE /bobf/cx_dac.
ENDIF.
"Try to pull the record at the specified index:
ASSIGN lr_t_data->* TO <lt_data>.
READ TABLE <lt_data> INDEX iv_index ASSIGNING <ls_row>.
IF sy-subrc EQ 0.
GET REFERENCE OF <ls_row> INTO rr_data.
ELSE.
RAISE EXCEPTION TYPE /bobf/cx_dac.
ENDIF.
ENDMETHOD. " METHOD get_node_row_by_assoc
ENDCLASS.
Note: In this simple example, we didn't bother to drill down to display the contents of the ROOT_LONG_TEXT node. However, if we had wanted to do so, we would have needed to create a separate service manager instance for the /BOBF/DEMO_TEXT_COLLECTION business object since the data within that node is defined by that delegated BO as opposed to the /BOBF/DEMO_CUSTOMER BO. Otherwise, the process is the same.
Modifying Customer Records
The process of modifying a customer record essentially combines logic from the display and create functions. The basic process is as follows:
- First, we perform a query to find the target customer record.
- Next, we use the
RETRIEVE*()methods to retrieve the node rows we wish to modify. Using the returned structure references, we can modify the target attributes using simple assignment statements. - Finally, we collect the node row changes into the modification table that is fed into
MODIFY()method provided by the/BOBF/IF_TRA_SERVICE_MANAGERinstance.
The code excerpt below shows how the changes are carried out. Here, we're simply updating the address string on the customer. Of course, we could have performed wholesale changes if we had wanted to.
CLASS lcl_demo DEFINITION CREATE PRIVATE.
PUBLIC SECTION.
CLASS-METHODS:
change_customer IMPORTING iv_customer_id
TYPE /bobf/demo_customer_id.
ENDCLASS.CLASS lcl_demo IMPLEMENTATION.
METHOD change_customer.
"Method-Local Data Declarations:
DATA lo_driver TYPE REF TO lcl_demo.
DATA lv_customer_key TYPE /bobf/conf_key.
DATA lt_mod TYPE /bobf/t_frw_modification.
DATA lo_change TYPE REF TO /bobf/if_tra_change.
DATA lo_message TYPE REF TO /bobf/if_frw_message.
DATA lv_rejected TYPE boole_d.
DATA lx_bopf_ex TYPE REF TO /bobf/cx_frw.
DATA lv_err_msg TYPE string.
FIELD-SYMBOLS:
<ls_mod> LIKE LINE OF lt_mod.
DATA lr_s_root TYPE REF TO /bobf/s_demo_customer_hdr_k.
"Try to change the address on the selected customer:
TRY.
"Instantiate the test driver class:
CREATE OBJECT lo_driver.
"Access the customer ROOT node:
lv_customer_key = lo_driver->get_customer_for_id( iv_customer_id ).
lr_s_root ?=
lo_driver->get_node_row( iv_key = lv_customer_key
iv_node_key = /bobf/if_demo_customer_c=>sc_node-root
iv_edit_mode = /bobf/if_conf_c=>sc_edit_exclusive
iv_index = 1 ).
"Change the address string on the customer:
lr_s_root->address = '1234 Boardwalk Ave.'.
APPEND INITIAL LINE TO lt_mod ASSIGNING <ls_mod>.
<ls_mod>-node = /bobf/if_demo_customer_c=>sc_node-root.
<ls_mod>-change_mode = /bobf/if_frw_c=>sc_modify_update.
<ls_mod>-key = lr_s_root->key.
<ls_mod>-data = lr_s_root.
"Update the customer record:
CALL METHOD lo_driver->mo_svc_mngr->modify
EXPORTING
it_modification = lt_mod
IMPORTING
eo_change = lo_change
eo_message = lo_message.
"Check for errors:
IF lo_message IS BOUND.
IF lo_message->check( ) EQ abap_true.
lo_driver->display_messages( lo_message ).
RETURN.
ENDIF.
ENDIF.
"Apply the transactional changes:
CALL METHOD lo_driver->mo_txn_mngr->save
IMPORTING
eo_message = lo_message
ev_rejected = lv_rejected.
IF lv_rejected EQ abap_true.
lo_driver->display_messages( lo_message ).
RETURN.
ENDIF.
"If we get to here, then the operation was successful:
WRITE: / 'Customer', iv_customer_id, 'updated successfully.'.
CATCH /bobf/cx_frw INTO lx_bopf_ex.
lv_err_msg = lx_bopf_ex->get_text( ).
WRITE: / lv_err_msg.
ENDTRY.
ENDMETHOD. " METHOD change_customer
ENDCLASS.
Next Steps
I often find that the best way to learn a technology framework is to see how it plays out via code. At this level, we can clearly visualize the relationships between the various entities and see how they perform at runtime. Hopefully after reading this post, you should have a better understanding of how all the BOPF pieces fit together. In my next blog post, we'll expand upon what we've learned and consider some more advanced features of the BOPF API.
67 Comments
