Crm 7.0 Bol Guide

Business Object Layer (BOL) Application Programming GuideWEBCUIF 7.0 Uwe Reimitz, Martin Wegmann © SAP AG Business Object Layer (BOL) Programming Guide Page 2 Table of Contents 1 2 3 4 5 5.1 5.2 ABSTRACT ............................................................................................................... 4 INTRODUCTION ...................................................................................................... 4 BOL VERSIONS ........................................................................................................ 4 OVERVIEW .............................................................................................................. 4 BASIC FEATURES OF THE BOL APPLICATION PROGRAMMING INTERFACE 5 Setting up a BOL Instance .....................................................................................................................................5 Component Sets and Components of the Generic Interaction Layer .............................................................6 5.3 Issue Queries.............................................................................................................................................................8 5.3.1 Simple Queries ..................................................................................................................................................8 5.3.2 Dynamic Queries ............................................................................................................................................ 11 5.4 Read Access to Business Objects using Entities............................................................................................... 13 5.4.1 Access Attributes............................................................................................................................................ 13 5.4.2 Access to related Entities ............................................................................................................................... 13 5.4.3 Further operations on entities ........................................................................................................................ 14 5.5 Changing Business Objects using Entities ........................................................................................................ 14 5.5.1 Transaction contexts....................................................................................................................................... 14 5.5.2 Locking Entities.............................................................................................................................................. 15 5.5.3 Modifying Entity Attributes........................................................................................................................... 15 5.5.4 Creating Entities ............................................................................................................................................. 16 5.5.5 Deleting Entities ............................................................................................................................................. 17 5.5.6 Execution of Entity Methods ......................................................................................................................... 17 6 ADVANCED FEATURES OF THE BOL APPLICATION PROGRAMMING INTERFACE ................................................................................................................. 19 6.1 6.2 Display mode support .......................................................................................................................................... 19 Standard Interface to Access Properties of Business Objects ....................................................................... 20 6.3 Working with Collections .................................................................................................................................... 21 6.3.1 Local and Global Iterations............................................................................................................................ 22 6.3.2 Searching......................................................................................................................................................... 23 6.3.3 Sorting............................................................................................................................................................. 23 6.3.4 Filtering ........................................................................................................................................................... 24 6.3.5 Changing the collection content .................................................................................................................... 25 6.3.6 Single and Multi Select Support.................................................................................................................... 25 6.3.7 Auto Cleanup Mode ....................................................................................................................................... 27 6.3.8 BOL Reset Survival Mode............................................................................................................................. 27 6.3.9 Specialized collections ................................................................................................................................... 28 6.3.9.1 Unique Type collections ............................................................................................................................ 28 6.3.9.2 Unique instance collections ....................................................................................................................... 28 Business Object Layer (BOL) Programming Guide Page 3 6.4 Transaction Handling .......................................................................................................................................... 29 6.4.1 Transaction context kinds .............................................................................................................................. 29 6.4.2 Transaction cycle............................................................................................................................................ 29 6.4.3 Collective transactions and Change tracking................................................................................................ 30 6.4.4 Tracking transaction state .............................................................................................................................. 31 6.5 Advanced Entity features .................................................................................................................................... 31 6.5.1 Input Readiness and Entity Property Modifiers ........................................................................................... 31 6.5.2 Excluding Entities from the Central Modify ................................................................................................ 31 6.6 6.7 Business Error Handling ..................................................................................................................................... 32 Mass operations using the BOL core................................................................................................................. 33 6.8 Buffering Issues..................................................................................................................................................... 33 6.8.1 Entity Properties ............................................................................................................................................. 34 6.8.2 Entity Relations .............................................................................................................................................. 34 6.8.3 Preloading BOL Views .................................................................................................................................. 34 6.8.4 Locking with Synchronization....................................................................................................................... 36 6.8.5 Buffering of Query results ............................................................................................................................. 36 6.9 BOL Reset.............................................................................................................................................................. 36 7 7.1 7.2 7.3 7.4 7.5 INTERFACE CLASSES ........................................................................................... 37 Core......................................................................................................................................................................... 37 Query Services....................................................................................................................................................... 37 Entity ...................................................................................................................................................................... 37 Collection................................................................................................................................................................ 37 Transaction Context............................................................................................................................................. 37 8 8.1 8.2 CHECKPOINT GROUPS ........................................................................................ 38 BOL checkpoint groups....................................................................................................................................... 38 Related checkpoint groups.................................................................................................................................. 38 9 9.1 9.2 INNER DETAILS AND DEBUGGING ..................................................................... 39 BOL Entities .......................................................................................................................................................... 39 Collections.............................................................................................................................................................. 40 Business Object Layer (BOL) Programming Guide Page 4 1 Abstract This document describes the runtime programming interface of the Business Object Layer (abbreviated as BOL). After you have read this document, you as a developer are able to create access and modify business data – like CRM Business Partner, CRM Product, HR data etc. - provided by the business object layer. The BOL may be used within all ABAP based applications – e.g. simple reports, dynpro- and business server page (BSP) applications. 2 Introduction The usage of the busines object layer and its uniform application programming interface (API) to access business data offers considerable advantages compared to the usage of various native APIs historically available for business objects: The object oriented BOL API is simple, uniform and easy to use The built-in buffer accelerates your applications Your programms are decoupled from any interface changes in the underlying business object specific APIs Development of WEBCUIF applications is made easy, since the BOL has been designed to work hand in hand with the UI parts of the framework It is possible to enhance the business object layer to cover business data not yet supported: After the corresponding business objects and query services have been modeled and implemented, you can use them at runtime. 3 BOL Versions The following list shows the various versions of the Business Object Layer: CRM 3.1 CRM 4.0 CRMIS 4.0 SAP_ABA 7.0 CRMUIF 5.1 CRMUIF 5.2 CRMUIF 6.0 WEBCUIF 7.0 First version – never in productive use First version use in a productive system Several improvements – introduction of separate display mode Relocation from CRM to ABA layer, first usage outside CRM Introducion of dynamic searches; whole CRM with BOL support Stabization and performance improvements Major internal changes for better performance on high number of objects Current version; Full Switch Framework support; Stable Core release 4 Overview The business object layer API consists of various interfaces and classes, you use to access business data. Most important are class CL_CRM_BOL_QUERY_SERVICE you use to select business objects, class CL_CRM_BOL_ENTITY representing entities as business object segments, the interface IF_BOL_TRANSACTION_CONTEXT to control transactional behavior, and IF_BOL_BO_COL providing access to collections holding entities. The lifetime of these objects in general is the whole session. The BOL API, however, provides a possibility to free used business objects and their memory. . classes and interfaces of the BOL Programming API Entities and related transactional contexts are centrally managed. 5 Basic Features of the BOL Application Programming Interface When you use the business object layer to work with business objects in an ABAP application you typically use code sequences similar to those indicated in the following chapters. The START_UP method takes the name of the GenIL component set you want to start as input parameter and starts the BOL.Business Object Layer (BOL) Programming Guide Page 5 Figure 1: Important objects. 5.1 Setting up a BOL Instance You create an instance of the business object layer by calling the static factory method of its core class: * Start BOL Core module DATA: lv_bol_core TYPE REF TO cl_crm_bol_core. lv_bol_core = cl_crm_bol_core=>get_instance( ). From now on you can use all services of the BOL and the component set loaded. This influeces their lifetime but ensures also instance uniqueness. Figure 2: It needs a few lines to start the BOL with an initial component set Since the BOL core CL_CRM_BOL_CORE follows the singleton design pattern you can just have one instance of it. Therefore it is sufficient to compare object instances for equality instead of object type and key. lv_bol_core->start_up( ‘MY_COMPONENT_SET’ ). Business Object Layer (BOL) Programming Guide Page 6 The START_UP method takes another optional parameter IV_DISPLAY_MODE_SUPPORT. etc. which makes all objects appear changeable in the user interface even without a lock (entity method IS_CHANGEABLE always return ABAP_TRUE). CRM Product. each providing specific business objects like CRM Business Partner with dependent objects and related queries.1 for further details. The lock state of an entity could be check via method IS_LOCKED. If the parameter IV_DISPLAY_MODE_SUPPORT is set to ABAP_TRUE the BOL follows the strict locking approach where only locked objects appear as changeable: See chapter 6. This means the BOL follows the optimistic locking approach. which is set to ABAP_FALSE by default. Figure 3: You’ll find BOL and GenIL Customizing in the SAP Implementation Guide 1 2 The expression ‘component set’ has replaced the former expression ’application’ GenIL = Generic Interaction Layer . CRM Order. The lock is automatically requested on the first attempt to really make a change.2 Component Sets and Components of the Generic Interaction Layer Each component set1 available is defined in view cluster CRMVC_GIL_APPDEF located in the SAP Implementation Guide and defines a set of so called GenIL2 components. 5. which relations. In order to find out which business objects and attributes. “BuilAddress” and “BuilActivity” stand for its address and related activities .Business Object Layer (BOL) Programming Guide Page 7 Figure 4: The GenIL component set SAMPLE consists of the GenIL components ‘BP’ and ‘SAMPLE’ Components of the Generic Interaction Layer (GenIL) are implemented ABAP classes. Figure 5: The Model Browser (transaction GENIL_MODEL_BROWSER) shows the technical names of business objects: “BuilHeader” in the screenshot above indicates a CRM Business Partner object as provided by the component set “SAMPLE” here. dependant objects. you may use the so called Model Browser (transaction GENIL_MODEL_BROWSER). queries and further services are provided by a component or component set. Get components loaded DATA: lv_obj_model TYPE REF TO if_genil_obj_model.Business Object Layer (BOL) Programming Guide Page 8 The following code snippet shows how to load additional components or component sets and how to check the components loaded so far: * Load additional component DATA: lv_component_name type crmt_component_name. lv_bol_core->load_component( lv_component_name ). That’s why you usually start your application with a search. 5. It is easy to check which GenIL components are available at runtime. 5. After this you may load component by component via LOAD_COMPONENT method. lv_component_name = 'ANOTHER_COMPONENT'. * Set a search criterion lv_query->set_property( iv_attr_name = ‘CARRID’ iv_value = ‘AA’ ). lv_component_set_name = 'ANOTHER_COMPONENT_SET'. Just start the BOL core with predefined component set EMPTY. Use its SET_PROPERTY . lv_obj_model_ TYPE REF TO cl_crm_genil_obj_model.3. lv_query = cl_crm_bol_query_service=>get_instance( ‘UIFSearchConnection’ ). lv_obj_model_ ?= lv_obj_model. * Execute query and receive result DATA: lv_result TYPE REF TO if_bol_entity_col.3 Issue Queries Before you can work with business objects or “entities” you have to find them.1 Simple Queries In order to fire a query you need to instanciate the query service you want to use and provide it with the search criteria: * Create a query service DATA: lv_query TYPE REF TO cl_crm_bol_query_service. lt_components_loaded = lv_obj_model_->get_components_loaded( ). which does not include any component. * Read a search criterion DATA: lv_carrid TYPE string. It is possible to load additional components * * Figure 6: Note: Via this technique it is also possible to work fully without predefined component sets. lv_bol_core->load_component_set( lv_component_set_name ). lv_obj_model = cl_crm_genil_model_service=>get_runtime_model( ). lv_carrid = lv_query->get_property_as_string( ‘CARRID’ ). Figure 7: Use the query service to fire a query The last coding example shows how to do this: First get an instance of the generic query service CL_CRM_BOL_QUERY_SERVICE via the factory method GET_INSTANCE. Load additional component set DATA: lv_component_set_name type crmt_genil_appl. lv_result = lv_query->get_query_result( ). lt_components_loaded type genil_component_tab. You use a query service object to receive a collection of entities that match the search criteria given. component set SAMPLE containing sample orders. such as the BOL browser. In a generic application. etc. the OrderQuery. … Figure 9: You have to specify an initial component set to be loaded when you start the BOL browser . lv_obj_model->get_object_list( EXPORTING iv_object_kind = if_genil_obj_model=>query_object IMPORTING ev_object_list = lt_query_names ).g. you may use the BOL Object Model Service to determine available query services of the component set and components loaded. * Determine available query services DATA: lv_obj_model TYPE REF TO if_genil_obj_model. e. lv_obj_model = cl_crm_genil_model_service=>get_runtime_model( ). Start the BOL Browser with the component or component set providing the objects you are interested in.Business Object Layer (BOL) Programming Guide Page 9 method to indicate the search criteria and its GET_QUERY_RESULT method to fire your query and to retrieve a result list of entities (represented by IF_BOL_ENTITY_COL). lt_query_names TYPE crmt_ext_obj_name_tab. As you can also see from the example it is also possible to retrieve search criteria from the query service. Figure 8: You may access the object model of the GenIL components loaded at runtime You may try out a query and many other methods of the BOL API described below with the so called BOL Browser (transaction GENIL_BOL_BROWSER) interactively. Select the query and enter search criteria. before you launch the query: Figure 10: Use the BOL browser to test your queries Double click on an object ID displayed in the List Browser to see the particular object with its attributes: Figure 11: The BOL browser is able to display entity properties . Dynamic queries allow also easy saving and restoring of queries as/from templates: * Save query as template lv_dyn_query->save_query_as_template( iv_query_id = ‘My Query’ iv_overwrite = abap_true ). * Set general query parameter for maximum number of hits lv_dyn_query->set_property( iv_attr_name = 'MAX_HITS' iv_value = '5' ). You can access them via method GET_SELECTION_PARAMS. etc. which returns directly the collection the dynamic query service it self operates on. In a normal program this makes not really sense. * Execute the query and receive result DATA: lv_result type ref to if_bol_entity_col. to specify the search criteria Search multiple values for one search criterion at the same time (logical OR) Save and retrieve predefined Searches with preset search criteria as templates identified with an arbitrary name * Get advanced query DATA: lv_dyn_query TYPE REF TO cl_crm_bol_dquery_service. with enhanced features: Besides the “Equal” operator you may use arbitrary operators like “Greater than”.Business Object Layer (BOL) Programming Guide Page 11 5. lv_dyn_query = cl_crm_bol_dquery_service=>get_instance( 'UIFAdvSearchFlight' ).. * Load query from template lv_dyn_query->load_query_template( iv_query_id = ‘My Query’ ). “Not Contains”. Figure 12: An advanced query offers enhanced search capabilities Because of the dynamic nature the selection parameters of a dynamic query are organized in a collection. However you high directly display the parameter collection in a UI where you normally want to group the criteria by the parameter name. Beside adding of selection parameters it is also possible to insert them. .3. lv_result = lv_advanced_query->get_query_result( ). * Add selection criteria: Maximum Seats > 5 lv_dyn_query->add_selection_param( iv_attr_name iv_sign iv_option iv_low iv_high = = = = = 'SEATSMAX' 'I' 'GT' “Greater than '100' '' ).. “Contains”. Less than”. You can iterate on this collection in order to check or change all selection parameters..1 the BOL supports also so called Dynamic Queries.2 Dynamic Queries With release CRMUIF 5.. Figure 13: Query templates are used to store and retrieve saved searches with predefined criteria . . Business Object Layer (BOL) Programming Guide Page 12 In order to display advanced queries in the Web UI special easy-to-use tags have been developed. Figure 14: Example for an advanced query display in the CRM Web UI . 5. * * lv_entity = lv_iterator->get_next( ). etc. DATA: lv_entity TYPE REF TO cl_crm_bol_entity.4. lv_carrid ?= lv_entity->get_property( ‘CARRID’ ). This navigation follows the relations given in the object model. * Use iterator to access entities in query result DATA:lv_iterator TYPE REF TO if_bol_entity_col_iterator.4. lv_flightdate = lv_entity->get_property_as_string( ‘FLDATE’ ). “Entity is UIFFlight here WHILE lv_entity IS BOUND. lv_flightdate TYPE string. lv_entity->get_properties( IMPORTING es_attributes = ls_attributes ). . see also section 6. lv_connid TYPE S_CONN_ID.Business Object Layer (BOL) Programming Guide Page 13 5. Method GET_PROPERTY_AS_STRING returns the value converted into and string. delete. Note that the methods are the same for all kinds of business objects. ENDWHILE. Get all attributes of an entity DATA: ls_attributes TYPE CRMS_BOL_UIF_TRAVEL_FLIGHT_ATT.1 Access Attributes The following coding example shows how to access entities of the query result and how to read their attributes. 5. you can use them in your application: Display its attributes on the user interface. lv_iterator = lv_result->get_iterator( ). Figure 15: Access BOL entities contained in a BOL collection and access attributes.4 Read Access to Business Objects using Entities After you get a list of entities from a query service. Note: This conversion considers some display formatting rules but not all. modify. This interface is provided not only from entities but also from query services to allow a uniform attribute access.2. * Access attributes of business objects selected DATA: lv_carrid TYPE ref to S_CARR_ID. lv_entity->get_property_as_value( EXPORTING iv_attr_name = ‘CONNID’ IMPORTING ev_result = lv_connid ). lv_entity = lv_iterator->get_first( ). Method GET_PROPERTY returns a pointer to the actual value were as method GET_PROPERTY_AS_VALUE provides the actual value as exporting parameter. So this resulting string is not intended for direct use in a business application UI! The attribute access is covered by generic interface IF_BOL_BO_PROPERTY_ACCESS. You can access attributes in three different formats.2 Access to related Entities The following coding example shows how to navigate from one entity to another. Get a 1:1 related entity DATA: lv_customer TYPE REF TO cl_crm_bol_entity. whereas the single business object scope transaction context exists for each root entity instance. Also the parent could only be returned for non-root objects. So if you follow an association to another root entity you cannot return via GET_PARENT! Furthermore it is possible to get to the root oentity of a business object via method GET_ROOT. The custom transaction context can be used to handle special situations. via method ALIVE. see also section 6. see section 6. * * In general we distinguish between 1:N and 1:1 relations. This happens either by calling methods SAVE and COMMIT or method REVERT on the context or via a higher order transaction context . where more than one but not all modified objects belong to a transaction. You can directly access model data. DATA: lv_booking TYPE REF TO cl_crm_bol_entity.4. Method GET_RELATED_ENTITIES works for both relations and returns always a collection. and delete entities in accordance to the BOL transaction model. lv_bookings = lv_flight->get_related_entities( iv_relation_name = ‘FlightBookRel’ ). The global transaction context exists always and is accessable via the BOL core instance. A single BO transaction context (fine granular context) is created either on request.1. In order to get back generic method GET_PARENT is provided. 5. which supports several kinds of so called transactional contexts to handle entity operations consistently.5 for further details. hidden.5. which means that it represents existing data. Further functions are described in the following sections. In this section we only use the global context. You can create.4. The global transaction context holds all modified root entities. Note: Since the parent needs not necessarily unique it would return the last used. lv_customer = lv_booking->get_related_entity( ‘BookCustomerRel’ ). Each single BO transaction context has to be finished once it was created. For convenience method GET_RELATED_ENTITY returns directly the related entity for 1:1 relations.1 Transaction contexts One of the most important aspects of BOL programming is to know how to modify data.3 Further operations on entities Beside the access to attributes and the navigation an entity provides further functionalities: You can check the changeability with methods IS_CHANGEABLE and IS_LOCKED. lv_booking = lv_bookings->get_first( ). or latest when the object gets locked. 5. You can check the properties of an attribute if it is changeable. You may check if an entity instance is still valid.5 Changing Business Objects using Entities 5.Business Object Layer (BOL) Programming Guide Page 14 * Get a list of 1:N related entities DATA: lv_bookings TYPE REF TO if_bol_entity_col. via method GET_TRANSACTION on an entity. mandatory … with method GET_PROPERTY_MODIFIER. For a discussion on the possible scopes of transaction contexts refer to section 6. This method returns the parent object. Get back to the parent lv_entity = lv_booking->get_parent( ). like the entity name with GET_NAME or the type of the attribute structure with GET_ATTR_STRUCT_NAME. modify. However. With display mode support switched on locking is mandatory. lv_booking->set_property( iv_attr_name = ‘SMOKER’ iv_value = ‘X’ ). The REVERT method always removes the lock.4. The setter only modifies properties in case the entity is locked. IF lv_booking->lock( ) = ABAP_TRUE. Once the transaction was saved it has to be finished via COMMIT or ROLLBACK.5. if not. The following code fragment shows how to modify a property of a booking.1. If you have not started a transaction before modifying properties it will be created automatically. This is simply done by using the set-methods of the entity. The only way to unlock the entity now is to finish this transaction context. So the lock request for an entity is always delegated to the corresponding root instance. For further details see also section 6.3 Modifying Entity Attributes Now we want to modify properties of entities. There is no way back after a failed save! So always check before hand! The end of a transactional context removes in general also the pending locks from the covert objects. Latest with setting a lock successfully a transaction context is created for the corresponding root entity instance. If only an intermediate save is required the COMMIT method allows keeping the locks via optional parameter IV_KEEP_LOCKS set to ABAP_TRUE. * Lock BOL entity DATA: lv_success TYPE abap_bool. send all changes to BO layer lv_bol_core->modify( ). 5. Normally this synchronization happens directly in the REVERT method. covered by the transaction will be rejected and the object returns to the last saved state from the database.Business Object Layer (BOL) Programming Guide Page 15 (global or customer). However. Lock an entity and modify a property * here booking entity with technical name ‘UIFBokking’ lv_booking = lv_flight->get_related_entity( ‘FlightBookingRel’ ). The current locking granularity of the BOL are the root object instances. try to do this.2 Locking Entities In the default optimistic lock mode. * 1. lv_success = lv_entity->lock( ). ENDIF. The current lock state of an entity could be checked via method IS_LOCKED. All changes. the set-methods of the entity check that the entity is locked and. 5. you should lock an entity before you are going to modify it. The following code fragment shows how to lock an entity. Figure 16: Lock an entity In case the lock was set the return value LV_SUCCESS is true ( ABAP_TRUE ).5. To do so the optional input parameter IV_SUPPRESS_BUFFER_SYNC needs to be set to ABAP_TRUE. Further the methods CHECK_SAVE_NEEDED and CHECK_SAVE_POSSIBLE allow to check before save if it is required and possible. . for performance reasons it might be better to do this synchronization in a lazy mode. see 5. * 2. 5. lv_transaction->commit( ). save and commit your changes lv_transaction->save( ). * 4. lv_ticket->set_property( iv_attr_name = ‘CARRID’ iv_attr_value = ‘AC’ ). get the implicitly created global transaction DATA: lv_transaction TYPE REF TO if_bol_transaction_context. Get factory for business object DATA: lv_flight_factory TYPE REF TO cl_crm_bol_entity_factory. ls_params-value = ‘AC’. Create child objects DATA: lv_booking TYPE REF TO cl_crm_bol_entity.5. Finally we save and commit the changes in step 4.4 Creating Entities The following code example shows how to create a root entity together with two related entities. In step 3 we get access to the automatically created global transaction context. * 5. Figure 18: Create root and related entities . ls_params TYPE crmt_name_value_pair. Figure 17: Modify properties of a related entity In step 1 we modify properties of an entity and in step 2 we communicate all modifications done so far to the Application Programming Interface (API) layer. The actual changeability of an attribute could be checked with method IS_PROPERTY_READONLY. * 3. APPEND ls_params TO lt_params. lv_ticket = lv_booking->create_related_entity( ‘BookTicketRel’ ). * 1. lv_booking->set_property( iv_attr_name = ‘CARRID’ iv_attr_value = ‘AC’ ).Business Object Layer (BOL) Programming Guide Page 16 * 3. lv_flight_factory = lv_bol_core->get_entity_factory( ‘UIFFlight’ ). Note: Independent of the lock state you can only modify changeable attributes. * 2. Create root entity DATA: lv_flight TYPE REF TO cl_crm_bol_entity. ls_params-name = ‘CARRID’. lv_booking = lv_flight->create_related_entity( ‘FlightBookRel’ ). Submit child objects created lv_bol_core->modify( ). lv_ticket TYPE REF TO cl_crm_bol_entity. lv_transaction->commit( ). Save and commit changes using single object transaction context DATA: lv_transaction TYPE REF TO if_bol_transaction_context lv_transaction = lv_flight->get_transaction( ). The given example works with or without display mode support. * 4. since the lock is explicitely set. lv_flight = lv_flight_factory->create( lt_params ). lv_transaction = lv_bol_core->get_transaction( ). * 6. lv_transaction->save( ). Build parameters to create an entity: * here a flight entity with technical name ‘UIFFlight’ DATA: lt_params TYPE crmt_name_value_pair_tab. For options to control what is send by the MODIFY method see section 6. The first one triggers directly a call of the underlying API. * Delete root entity lv_flight->delete( ).0 release method type EXECUTE2 was introduced.2. lv_transaction = lv_bol_core->get_transaction( ). So in the second case it is necessary to trigger the API call explicitly via calling the MODIFY method of the BOL core.5.5. Immediately after the method CL_CRM_BOL_CORE->MODIFY has been executed and the underlying API confirmed the deletion the entity is deleted from the BOL buffer. After the deletion any further access to the entity instance might lead to an exception CX_BOL_EXCEPTION. This is only after finishing the transaction the case. With the CRMUIF 6. . The deletion is written to the database with an internal COMMIT WORK.6 Execution of Entity Methods In order to perform special business functionality it is possible to call special methods on an entity. Even after sending an newly created entity to the API it is not yet persistent. For root object instances the call of the DELETE method is directly sent to the API where the complete aggregation hierarchy is deleted. 5. 5. lv_bol_core->modify( ). This is published from the entity instance by raising event DELETED. The persistence state of an entity could be checked via method IS_PERSISTENT. It returns an arbitrary DDIC type instead of a collection. Figure 19: Delete root entity In case of a child object the deletion is not automatically sent to the API. Without this call the created child objects will only exist in the BOL buffer and never get saved. Note: For performance reasons a newly created entity has always sending deactivated. Both can have an arbitrary set of import parameters. This technique is used to collect fine granular changes and to bundle them before sending to the API to process and evaluate them together. since in general it does not make sense to send empty objects.5 Deleting Entities Similar to entity creation we have to distinguish between the deletion of root objects and the deletion of dependant or child objects. Entities can have two kinds of methods. You have to trigger this explicitly by calling the MODIFY method of the BOL core. which have been modeled and implemented for a particular object type. Method EXECUTE may return an entity collection of result objects.5. * Delete child object lv_booking->delete( ). lv_transaction->commit( ). lv_transaction->save( ). Figure 20: Delete related entity As you can see from the example in this case you also have to save and commit the transaction in order to persist the deletion. DATA: lv_transaction TYPE REF TO if_bol_transaction_context. which sends the changes to the underlying generic interaction layer.Business Object Layer (BOL) Programming Guide Page 17 It is important to distinguish between the creation of root objects via the entity factory and the creation of dependent or child objects with method CREATE_RELATED_ENTITY. So in order to send it with MODIFY you need either to set at least one attribute or activate the sending explicitely. the second one in general not (depending on the model). .. . * An exception is received if method has indicated an error * and has not returned more than one entity.... * Error handling CATCH CX_CRM_BOL_METH_EXEC_FAILED. lv_items->execute( iv_method_name = ‘RenumberItems’ ). These changes lead to automatic locking and the creation of an associated transaction context. ENDTRY. TRY. Figure 21: Execute an entity method to perform special business functionality Note: Before an entity method is processed all pending changes in the BOL buffer are transferred automatically to the API with an implicite MODIFY. Entity methods may also include changes of a business object. * Execute entity method DATA: lv_items TYPE REF TO cl_crm_bol_entity. lt_param TYPE crmt_name_value_pair_tab. ls_param-name = ‘PROCESS_TYPE’. lv_result = lv_order_header->execute( iv_method_name = ‘createFollowUp’ it_param = lt_param ). * . lv_result TYPE REF TO if_bol_entity_col. ls_param-value = ‘TSRV’.Business Object Layer (BOL) Programming Guide Page 18 The following coding example shows the usage. append ls_param to lt_param. with input parameters and a list of BOL entities returned DATA: ls_param TYPE crmt_name_value_pair. Any attempt to change properties. ENDIF. * Execute query and access entity DATA: lv_entity type ref to cl_crm_bol_entity.1 Display mode support With SAP_ABA 7. “Entity is in now display mode * Switch to change mode and change entity lv_entity->switch_to_change_mode( ). “Reread and lock entity IF lv_entity->is_changeable( ) = abap_true.. lv_bol_core = cl_crm_bol_core=>get_instance( ). lv_entity->set_property_as_string( iv_attr_name = ‘PROPERTY_NAME’ iv_value = ‘New Value’ ). If no lock could be obtained the entity remains in display mode. 6. Such attempts can be monitored via checkpoint group BOL_ASSERTS under subkey READ-ONLY VIOLATION. .. In order to do changes it is necessary to switch the entity explicitly to “Change Mode” first: This is either done by calling method SWITCH_TO_CHANGE_MODE or method LOCK. lv_bol_core->start_up( iv_appl_name = ‘MY_COMPONENT_SET’ iv_display_mode_support = ABAP_TRUE ).0 the Business Object Layer optionally supports the so called “Display Mode” for entities.Business Object Layer (BOL) Programming Guide Page 19 6 Advanced Features of the BOL Application Programming Interface The following sections describe special features of the BOL API. to create or delete dependent objects is ignored. lv_entity = . The current state of an entity can be checked with method IS_CHANGEABLE. It is turned on if the BOL core is started with the parameter IV_DISPLAY_MODE_SUPPORT = ABAP_TRUE. * Start BOL core with display mode support DATA: lv_bol_core TYPE REF TO cl_crm_bol_core. which is with display mode support equal to method IS_LOCKED. In display mode a call of method IF_BOL_BO_PROPERTY_ACCESS~IS_PROPERTY_READONLY on an entity returns ABAP_TRUE for each property. Figure 22: Usage of the BOL core’s change mode When an entity is locked its properties are read anew to make the latest data available. lv_city = lv_bo->get_property_as_string( ‘City’ ). * up cast and generic access lv_bo ?= lv_query. Figure 24: Usage of the IF_BOL_BO_PROPERTY_ACCESS interface . lv_bo TYPE REF TO if_bol_bo_property_access. * Set property of BOL entity DATA: lv_entity TYPE REF TO cl_crm_bol_entity lv_entity->if_bol_bo_property_access~set_property( iv_attr_name = ‘CITY’ iv_value = ‘Walldorf’ ).2 Standard Interface to Access Properties of Business Objects In order to access properties of BOL entities and query services (among others) you make use of their IF_BOL_BO_PROPERTY_ACCESS interface methods. The interface offers a standard means to work with BOL objects. * up cast and generic access lv_bo ?= lv_entity. * Get search criterion of BOL query DATA: lv_query TYPE REF TO cl_crm_bol_query_service. «interface» IF_BOL_BO_PROPERTY_ACCESS CL_CRM_BOL_QUERY_SERVICE CL_CRM_BOL_ENTITY Figure 23: The interface IF_BOL_BO_PROPERTY_ACCESS provides a standard means to access properties of BOL objects The interface is implemented by entities. Note that it is possible to cast many BOL object to an instance of IF_BOL_BO_PROPERTY_ACCESS. lv_query = cl_crm_bol_query_service=>get_instance( ‘QUERY_NAME’ ). simple and dynamic query services. * Short form using alias lv_city = lv_query->get_property_as_string( ‘City’ ). lv_city = lv_query->if_bol_bo_property_access~get_property_as_string( ‘City’ ). * Short form using alias lv_entity->set_property( iv_attr_name = ‘CITY’ iv_value = ‘Walldorf’ ). lv_bo->set_property( iv_attr_name = ‘CITY’ iv_value = ‘Walldorf’ ). lv_city TYPE string.Business Object Layer (BOL) Programming Guide Page 20 6. and parameters of dynamic queries. GET_NEXT. lv_sex = lv_bo->get_property( ‘SEX’ ). or ADD. GET_CURRENT.3 Working with Collections The BOL API offers several collections for application use.3. 2 = Male lv_bo ?= lv_person. With release SAP_ABA 7. This is available with release CRMUIF 5. CL_CRM_BOL_COL is the most generic one and can be used to hold all instances implementing the the standard property access interface IF_BOL_BO_PROPERTY_ACCESS. The available events are: FOCUS_CHANGED: Raised.6 for details. All collections provide events to track the collection state. Especially for handling entities exists the spezialized version CL_CRM_BOL_ENTITY_COL implementing the also specialized collection interface IF_BOL_ENTITY_COL.Business Object Layer (BOL) Programming Guide Page 21 Besides generic getter and setter methods to read and modify business object properties the interface offers methods to receive the text for a key-code value. lv_bo TYPE REF TO if_bol_bo_property_access. . * Get key code DATA: lv_person TYPE REF TO cl_crm_bol_entity. “Defines values 1 = Female. “Key code * Get property text for key code: * -> ‘Male’ or ‘Female’ translated in current language DATA: lv_sex_text TYPE string. Figure 25: Access property texts of key codes The text is taken from the domain values if available or has to be provided by the underlying GenIL component.9.3.0 collections implement the additional interface IF_BOL_BO_COL_MULTI_SEL for multi selection support.g. 6. CLEAR . It implements the standard collection interface IF_BOL_BO_COL. which are the subject of section 6. Figure 26: Collection types and their interfaces The collection interfaces offer a bunch of methods to work with collections – e.1. if the focus element in single selection mode changes. see section 6. There exist several further specializations of these classes. SORT . lv_sex TYPE REF TO bu_sexid. lv_sex_text = lv_bo->get_property_text( ‘SEX’ ). GET_FIRST. Iterators are unmanaged subobjects of a collection. In this mode the collection tries to restore all entities in the collection after a BOL reset. lv_query TYPE REF TO cl_crm_bol_query_service.4).8 for further details 6. which is subject of the event. “Global iteration “ moves focus * Local iteration DATA: lv_iterator TYPE REF TO if_bol_bo_col_iterator. It is also not possible to determine afterwards on which collection an iterator will operate. “Local iteration does not ENDWHILE. lv_iterator = lv_collection->get_iterator( ).. if a object is removed from the collection. All collections provide further an auto cleanup mode. . In the default single selection mode each non-empty collection has a well-defined focus object.. lv_property_access TYPE REF TO if_bol_bo_property_access. Without this option to access the creating collection directly. which is published by the event FOCUS_CHANGED of the collection. * Create collection DATA: lv_collection TYPE REF TO cl_crm_bol_bo_collection.1 Local and Global Iterations All collection types support global and local iteration. Raised.Business Object Layer (BOL) Programming Guide Page 22 BO_ADDED BO_DELETED Raised.3.3. Beside local iteration to avoid changes of the collection focus iterators provide also additional features like searching by property (section 6. see section 6. The standard interface IF_BOL_BO_COL_ITERATOR for general access is provided by all collections. If possible the events provide also additional information about the object. iterator method GET_COPY allows to get a further iterator on the collection without knowing it. if a new object is added to the collection. If you want to iterate on the collection without moving the focus (and without triggering time-consuming follow-up processes) you have to use local iteration. “ move focus Figure 27: Collection types and their interfaces There are two iterator interfaces. .3. see section 6.3.2) or filtering (section 6. CREATE OBJECT lv_collection. * Global iteration lv_property_access = lv_collection->get_next( ). Initially the first object has the focus. * Add item and make it current lv_collection->if_bol_bo_col~insert( iv_bo = lv_query iv_index = 1 iv_set_focus = ABAP_BOOL ). lv_property_access = lv_iterator->get_next(). Collections of type CL_CRM_BOL_ENTITY_COL support further interface IF_BOL_ENTITY_COL_ITERATOR for more strict typed access. Furthermore collections provide a reset survival mode.7 for details. Any global iteration moves the focus. Once you retrieve an iterator the collection will not remember it. In this mode deleted entities will automatically removed from the collection. To do so you request an iterator object from the collection and use this to iterate. lv_property_access = lv_iterator->get_first( ) WHILE lv_property_access is bound.3. The first object. The optional parameter IV_STABLE = ABAP_TRUE is used to perform stable sorting.Business Object Layer (BOL) Programming Guide Page 23 6. This means also that conversion exits are not considered! Note: Text-type components are sorted according to the locale of the current text environment. The parameters are taken in the given sequence. Figure 29: Collections can be sorted Note: The sorting itself is alphanumerical based on the internal format of the attribute. is returned. See also section 6. * Find by property DATA: lv_persons TYPE REF TO cl_crm_bol_entity_collection. Without this addition. The local iterator interfaces support the search for a single property.2. Figure 28: Find collection item by property and set focus 6.2 Searching The collections provide the method FIND to search a given business object in the collection.3 Sorting Collections can be sorted with the SORT method. You can search by index or business object instance. lv_male TYPE REF TO cl_crm_bol_entity. lv_persons->sort( iv_attr_name = ‘SEX’ iv_sort_order = IF_BOL_BO_COL=>SORT_DESCENDING ). where only one is used for the search at a time. * Sorting by gender DATA: lv_persons TYPE REF TO cl_crm_bol_entity_collection. Via this method the collection itself is sorted and will stay in the resulting sort order. It is not possible to undo the sort operation. lv_male = lv_iterator->find_by_property( iv_attr_name = ‘SEX’ iv_value = 2 ). where the gender key SEX (1 or 2) was used. This is provided by the method FIND_BY_PROPERTY. Neither the global nor the local collection focus is influenced by this operation. whose property has the given value. The mandatory parameter IV_ATTR_NAME specifies the property the collection is to be sorted for. The method takes two parameters.3. * Set collection focus on the entity found lv_persons->find( iv_bo = lv_male ). lv_iterator TYPE REF TO if_bol_bo_col_iterator. The following code sample shows the sorting of a collection of persons by the gender. now the gender text (‘Male’ or ‘Female’) is used for sorting. the sequence is not retained and multiple sorting of a table using the same sort key results in a different sequence each time the table is sorted. lv_iterator = lv_persons->get_iterator( ).3. . If you do not specify IV_SORT_ORDER the sort order is ascending. This means if you provide an index and an instance only the index is used. which means that the relative sequence of lines that does not change in the sort key remains unchanged in the sort. Instead of the prior example. If found it is returned and also the focus is set to this collection entry. The optional parameter IV_USE_TEXT_RELATION = ABAP_TRUE allows you to sort using the text related to a key in case the attribute is just a key and the key-text relation is known. The text used in the sorting will be retrieved via GET_PROPERTY_TEXT. 3. . The filter functionality is equal for both iterator types IF_BOL_BOL_COL_ITERATOR and IF_BOL_ENTITY_COL_ITERATOR. The optional parameter IV_PATH_2_SUBOBJECT allows you to sort the collection base on an attribute of a related child object. lv_filter TYPE REF TO if_bol_bo_col_iterator. lv_filter->filter_by_property( iv_attr_name = ‘SEX’ iv_value = 1 ). Figure 30: Collections can be filtered The code sample above shows the filtering of a collection of persons by gender. A filter is only applied via the iterator(s). or simply on more the one field. During the sort process its method IS_A_GREATER_B is called whenever two values are compared. In case of a 1: N relation the first object will be taken. The following code sample shows the sorting of a collection of flights by the name of the customers. lv_filter = lv_persons->get_iterator( ). So the navigation along a fixed path of relations does not need to be implemented in method IS_A_GREATER_B. Optional you can chosse the filter mode. * Filtering a collection of persons for females only DATA: lv_persons TYPE REF TO cl_crm_bol_bo_collection. To do so an instance of IF_BOL_COL_SORTING can be provided.3. If more then one relation should be followed the relation need to be separated by a slash ‘/’. The standard ABAP operator CP will be used for comparison. Therefore all examples will just concentrate on the standard iterator IF_BOL_BOL_COL_ITERATOR. 6.1). The gender could be female (attribute SEX = 1) or male (attribute SEX = 2). * Sort collection containing UIFFlight entities lv_flights->sort( iv_attr_name = ‘NAME’ iv_path_2_subobject = ‘FlightBookRel/BookCustomerRel’ ). Thus the collection it self is never changed by the filtering. When building the sort table for each flight the relation FlighBookRel will be follow to UIFBooking and from there relation BookCustomerRel to UIFCustomer from which attribute NAME is taken. As you can have any number of iterators for a collection it is also possible to have any number of filters on it in parallel. it is possible to control the sorting externally. or should base on not supported criteria. Since FlightBookRel is a 1: N relation only the first booking is considered.Business Object Layer (BOL) Programming Guide Page 24 * Sort collection containing UIFFlight entities lv_flights->sort( iv_attr_name = ‘SEX’ iv_use_text_relation = ABAP_TRUE ). You have to specify the name of the attribute and a value or value pattern as filter criteria. Normally the actual attribute values of the given attribute IV_ATTR_NAME are passed as IV_A and IV_B. In case pseudo attribute name IF_BOL_COL_SORTING=>CUSTOM is passed to whole entity instance is passed instead. The attribute name given with IV_ATTR_NAME must fit to the addressed target object. This is also supported in combination with parameter IV_PATH_2_SUBOBJECT. In order to set a filter an iterator for the collection is required (see section 6. The given relation or relations should be 1:1 relations. A filter could be set using method IF_BOL_BOL_COL_ITERATOR~FILTER_BY_PROPERTY. After setting the filter criteria the iterator will only operate on objects matching the given criteria. in the example: persons being female.4 Filtering Collections can be filtered using an iterator. The attribute value can be given as pattern. If the desired sort order is not alphanumerical. Implement this method and provide the interface to influence the sort order as needed. Each call will refine the result according to the addition filter criteria. especially operations on the whole collection. reflecting all changes to the collection and there entities directly. Also filters might get outdated. Additionally the following mass operations are supported: IF_BOL_BO_COL~ADD_COLLECTION Appends the content of a given collection to the collection. Note: When adding object to the collection the sort order is not automatically preserved. IF_BOL_BO_COL~CLEAR Removes all objects from the collection. see section 6.3. The added/removed objects will not be published by the event. In the Multi Selection Mode it is possible to mark more than one entry at a time . The addition and removal of objects to/from the collection can be monitored via the collection events BO_ADDED and BO_DELETED. In the same order you build up the filter by adding criterias you can delete it again. such as GET_SIZE.5 Changing the collection content The content of a collection could be changed via the following single object operations: IF_BOL_BO_COL~ADD Append an object to the collection. For each iterator operation the filter is interactively applied vthe the original collection computing the result. and IF_BOL_BO_COL~REMOVE Remove an object from the collection. This applies especially to the iterator methods SIZE and GET_BY_INDEX. The presents of a filter colud be checked via public attribute IF_BOL_BO_COL_ITERATOR~FILTER_ACTIVE.3. The default filter mode is IF_BOL_BO_COL_ITERATOR =>FILTER_MODE_CACHED. the previous one looses focus. All occurrences of the object will be removed. The alternative filter mode is IF_BOL_BO_COL_ITERATOR =>FILTER_MODE_INTERACTIVE. The added/removed object will be published by the event.4 6.Business Object Layer (BOL) Programming Guide Page 25 All iterator methods will respect the filter. As for the single object operations the addition and removal of objects to/from the collection can be monitored via the collection events BO_ADDED and BO_DELETED. Consequently this mode should only be used in read-only case. Thus the operations get less performant. However. 6. Thus in combination with iterator method GET_COPY it is also possible to store filter criteria in an iterator independent of a collection. The downside of this approach is that the filter result might get invalid when original collection or the contained entities get changed. the result will always be correct. see also section 6. Method DELETE_FILTER removes per default only the last filter criteria.3.3.6 for details.6 Single and Multi Select Support BOL collections support two different modes for entry selection: In the so called Single Selection Mode it is possible to select a single entry at a time: As soon as another entry is selected. In this mode the iterator stores a filtered copy of the original collection. All operation might change the focus object of the collection. Thus operations on the filtered collection are as performant as without filter. IF_BOL_BO_COL~INSERT Insert an object into the collection at a given position. which behave now different to there counterparts directly on the collection. Here the iterator stores only the filter criteria and operates still on the original collection. Method ADAPT_FILTER allows you to adapt the filter criteria of your iterator the the once of a given iterator. With optional parameter IV_ALL = ABAP_TRUE can can remove all filters at once. In order to setup a more complex filter you can call method FILTER_BY_PROPERTY several times. UNMARK. you may use the methods of the interface IF_BOL_BO_COL_MULTI_SEL to mark and unmark entries and to check. which could be ABAP_TRUE or ABAP_FALSE. In case the focus object is removed. * Wrong code lv_flight = lv_flights-> get_first( ) WHILE lv_flight is bound. In single selection mode the selected element is accessed with the methods IF_BOL_BO_COL~GET_CURRENT returns the selected element IF_BOL_BO_COL~GET_CURRENT_INDEX returns the index of the selected element IF_BOL_BO_COL~PUBLISH_CURRENT publishs the selected element via event IF_BOL_BO_COL~FOCUS_CHANGED and it is implicitly set with IF_BOL_BO_COL~FIND IF_BOL_BO_COL~GET_NEXT IF_BOL_BO_COL~GET_PREVIOUS moves focus either to given index or object moves focus to the next element and returns it moves focus to the previous element and returns it Note: In single selection mode the current or focus element is always defined. In all other cases it can change the focus if optional parameter IV_SET_FOCUS is given as ABAP_TRUE.Business Object Layer (BOL) Programming Guide Page 26 The current selection mode can be checked with the public collection attribute IF_BOL_BO_COL~MULTI_SELECT. except the collection is empty. When multi selection mode has been switched on. and it can be set with method IF_BOL_BO_COL~SET_MULTI_SELECT. Only in case it was the last in the collection (and the collection is not empty). Method IF_BOL_BO_COL~ADD changes the focus in case the collection was empty before. GET_MARKED). IF lv_flight->get_property_as_string( ‘CARRID’ ) = ‘AC’. Lv_flight TYPE REF TO cl_crm_bol_entity. which entries have been marked (IF_BOL_BO_COL_MULTI_SEL~MARK. In case the removed object(s) has/have not the focus it remains unchanged. the focus moves to the previous object. Method IF_BOL_BO_COL~CLEAR will change the focus to nothing. In multi selection mode the collection methods mentioned above behave different: IF_BOL_BO_COL~GET_CURRENT IF_BOL_BO_COL~GET_CURRENT_INDEX IF_BOL_BO_COL~PUBLISH_CURRENT IF_BOL_BO_COL~FIND IF_BOL_BO_COL~GET_NEXT IF_BOL_BO_COL~GET_PREVIOUS returns the last selected element returns the index of the last selected element does nothing finds. The same applies for method IF_BOL_BO_COL~INSERT. The following code sample demonstrates a possible coding mistake based on this behaviour and its correct solution: * Example: Remove all flights from Air Canada (AC) from the collection DATA: lv_flights TYPE REF TO if_bol_entity_collection. Note: Special attention should be payed to the focus handling of method IF_BOL_BO_COL~REMOVE. The methods of the interface IF_BOL_BO_COL_MULTI_SEL are switched off. eventually selects and returns an element does nothing does nothing Also changes to the collection may change the the focus. . the focus is moved to the next in the collection (in fact the index of the focus object remains unchanged). Business Object Layer (BOL) Programming Guide Page 27 lv_flights->remove( iv_entity = lv_flight ). So when the removal happens the next object gets the focus automatically. the recreation after reset is limited to root and access entities.3. it is not active by default. it is necessary to clear a collection (call of method IF_BOL_BO_COL~CLEAR) when it is not needed any more: Otherwise the garbage collector could not delete the collection since it is referenced in the event handler table of its entities.7 Auto Cleanup Mode Auto clean up mode for a collection ensures that deleted entities are automatically removed from the collection. ENDWHILE. some may have to protect their content. Note: If auto cleanup mode is switched on. ENDWHILE. Calling method IF_BOL_BO_COL~ACTIVATE_AUTOCLEANUP activates this function. Although this is OK for most collections at certain times. lv_flight = lv_flights->get_next( ).3. especially if it is essential for the further progress of the application. In case you just log assert violations they will get collected under subkey COLLECTION_NOT_RESET_COMPLIANT. lv_flights->remove( iv_entity = lv_flight ). The current state of the collection is indicated by the public attribute IF_BOL_BO_COL~AUTOCLEANUP. which is ABAP_TRUE if auto cleanup is active. ENDIF.0 onwards. IF lv_flight->get_property_as_string( ‘CARRID’ ) = ‘AC’. lv_flight = lv_flights->get_current( ). * Correct code lv_flight = lv_flights-> get_first( ) WHILE lv_flight is bound. Because of the global iteration the REMOVE always effects the current focus element. Furthermore the reset is propagated to the underlying GenIL components in order to cleanup their buffers. To reduce this negative impact the recreation is delayed from release WEBCUIF 7. This might lead to serious memory consumption issues! 6. . To avoid negative runtime impacts of this safety check it needs to be activated via checkpoint group BOL_ASSERTS using transaction SAAB (Assertions and Breakpoints). As a consequence the (last) selected element may change automatically in this case. 6. You can use method IF_BOL_BO_COL~SET_RESET_SURVIVAL_MODE to indicate that the root and access entities in the collection should be kept and recreated afterwards. lv_flight = lv_flights->get_next( ). Note: The use of the reset survival mode limits the effect of the BOL reset and could lead to considerable runtimes of the reset. ENDIF. Since the automatic removal of deleted entities is not always necessary and this feature might lead to serious memory consumption issues (due to the creation of lifetime dependencies). Thus the content of the collection could be checked for reset complaintness when turning on the reset survival mode. which destroys all BOL entitites and as a consequence clears all collections with auto cleanup activated. the affected collection would remain in memory probably until the next BOL reset operation or session end. As already stated above. ELSE.8 BOL Reset Survival Mode In order to release unused memory the application from time may trigger a BOL reset. Thus an unconditional call of GET_NEXT would left out some objects from the check. which focuses only on strikter typed access to entities. If the conversion is not possible it will result in exception CX_BOL_EXCEPTION. The collection will be build out of all resulting collections of method GET_RELATED_ENTIES on each entity in the collection. while lv_entity is bound. Endwhile. in single selection mode only the focus object would be taken. Furthermore optional parameter IV_MARKED_ONLY allows restricting the set of parent entities to the marked entities in multiselection mode. Static method CL_CRM_BOL_ENTITY_COL_UT=>CONVERT allows you to convert an existing collection to a unique type collection preserving its content and state. lv_children ?= lv_entity->get_related_entities( iv_relation_name = ‘MyRelation’).9. lv_iterator = lv_collection-> get_iterator( ). lv_result = lv_ut_collection->get_related_entities( iv_relation_name = ‘MyRelation’ ).3. * Get all children of all entities of a collection – standard implementation DATA: lv_collection TYPE REF TO cl_crm_bol_entity_col. All methods adding objects to the collection check the uniqueness and will ignored objects already part of the collection. This makes it easy to collect objects in a collection without the risk of duplicates.1 Unique Type collections The further specialized entity collection CL_CRM_BOL_ENTITY_COL_UT limits the content of the collection to a single entity type. . .3. Violations will lead to exception CX_BOL_EXCEPTION. 6. lv_entity = lv_iterator->get_first( ).2 Unique instance collections The specializations CL_CRM_BOL_UNIQUE_BO_COL and CL _CRM_BOL_UNIQUE_ENTITY_COL are provided to make it easy to control that each BO or entitiy instance is only stored once in a collection. The desired type is given to the constructor of the collection and all methods adding objects to the collection will respect it. Since the type of all entities in the collection is equal the collections can offer mass operations on its content. So far only navigation is supported.9 Specialized collections Beside the simple specialization CL_CRM_BOL_ENTITY_COL. * Get all children of all entities of a collection – using unique type coll DATA: lv_ut_collection TYPE REF TO cl_crm_bol_entity_col_ut. exist further specialized collections providing also additional functionalities. 6. Note: Method ADD_COLLECTION is not supported by this collection type. lv_children TYPE Ref TO if_bol_entity_col.3. The collection method supports all features of the entity method.Business Object Layer (BOL) Programming Guide Page 28 6. CREATE OBJECT lv_result. Method GET_RELATED_ENTIES will return a collection of related entities for a given relation. lv_iterator TYPE REF TO if_bol_entity_col_iterator. lv_entity TYPE_REF TO cl_crm_bol_entity. lv_result->add_collection( lv_children ). lv_ut_collection = .9. lv_result TYPE REF TO cl_crm_bol_enity_col.cl_crm_bol_entity_col_ut=>convert( lv_collection ). Single BO transaction contexts are managed by the global transaction manager. The instance associated with a root entity is unique for a transaction cycle. Once the transaction has finished a new transaction context is associated with the root entioty and the prior one becomes usesless. which needs to be instanciated as needed. The lock event is publish by the BOL core and the transaction manager createst a single BO transaction context for the locked BO. the general life cycle is equal. This could be repeated many times. including other custom transaction contexts. In the success case the transaction is closed by calling method COMMIT. Per default the buffer is directly synchronized with the latest save state from . but the BOL tries to lock the object immediately again. The setting of the lock is published by this single BO transaction context via event LOCK_SET. However. The custom transaction context for any scope inbetween the two above. Now it is possible the change the BO. Before saving you can call the business logic for further consistence check via method CHECK_SAVE_POSSIBLE. transaction context for this BO it is used. The methods of the transaction contexts act always on its whole content. The global transaction context is managed by the BOL core and does not change in the whole session.4. Alternatively you can retrieve transpaction contexts per root entity instance from the global transaction context via method GET_TX_CONTEXT. Custom transaction contexts are not centrally managed. This instance is stored in the transaction manager. This will reset the buffer state and release the lock. It could be easily retrieved via method GET_TRANSACTION of any entity belonging to this BO. Actually the lock is released in any case.1 the creation and lifetime of the three transaction context kinds are different. In the unlikely case of an error during save it needs to be finished with method ROLLBACK.4. beforehand created. It could be retrieved via the BOL core method GET_TRANSACTION. 6. A transaction starts latest with locking the first object. But this case should be avoided by processing all necessary checks beforehand in CHECK_SAVE_POSSIBLE. Note: Pending Changes in the BOL buffer are not recognized by this method! In order to close the transaction cycle you can save or reset the changes. In case there is already an. This method will return a success indicator. The actual save of the data is initiated with calling method SAVE. All changes made via the BOL API are collected in the BOL buffer.4 Transaction Handling 6. There are three different scopes of transaction contexts: The Global Transaction Context covering all changes. Existence of changes that need to be saved can be checked via method CHECK_SAVE_NEEDED.2 Transaction cycle As mentioned in section 6. When calling COMMIT you can specify that you want to keep the lock via optional parameter IV_KEEP_LOCK = ABAP_TRUE.Business Object Layer (BOL) Programming Guide Page 29 6. Then any transaction context could be added to it. A custom transaction context is an instance of class CL_CRM_BOL_CUSTOM_TX_CTXT.4. Only with calling the MODIFY method of the BOL core will communicate the changes to the underlying business logic. If any change is expepted there it is publish from the BOL core to the transaction manager and remembered in the associated single BO transaction context. The Single Business Object Transaction Context covering the changes of a single business object instance.1 Transaction context kinds Transactions are handled via transaction contexts represented by interface IF_BOL_TRANSACTION_CONTEXT. Note: The BOL COMMIT always forces a synchronous database update! In case you deside to reset all changes you have to call the method REVERT. BOL transactions handle all database updates synchronously. Save and commit both single BO transactions together my_tx_context->save( ). thus not only single BO transactions contexts but aolso other custom transaxtion context may added.. lv_entity2 TYPE REF TO cl_crm_bol_entity. which will lead to an exception! To be save you might check the entity state before hand via method ALIVE or you program securely with a TRY. This collecting mode is switched on via method START_RECORDING and with STOP_RECORDING switched off again. construct. and the global transaction context starts a new cycle anyway. If the first one is saved but the second one not. it is up to the application to handle them. Since such dependencies are not automatically tracked. ENTRY. Beside this explite adding of transaction contexts it is also possible to monitor changes for a certain time periode and to collect all associated transaction contexts. Note: In the lazy mode it might happen that you access an already deleted entity. After this cycle a single BO transaction context becomes obsolete and could not be used any further. lv_tx_ctxt = lv_entity1->get_transaction( ). In case a transaction context contained in the custom transaction context is finished independently it is automaitally removed form the custom transaction context. Because of this feature a custom transaction context will be empty after it has finished or the global transaction has been finished. my_tx_context->add_tx_context( lv_tx_ctxt ). my_tx_context->add_tx_context( lv_tx_ctxt ). Use it to build one transaction context consisting of more than one single BO transactions. The following coding lines give a little example: * 1. my_tx_context->commit( ). lv_tx_ctxt = lv_entity2->get_transaction( ). Figure 31: The custom transaction context can be used to form transactions consisting of more than one root object With method ADD_TX_CONTEXT you can add other transaction contexts to your custom context. CREATE OBJECT my_tx_context. the database is in an inconsistent state.4.Business Object Layer (BOL) Programming Guide Page 30 the database. . Therefore it is not necessary to remove it explicitely via method REMOVE_TX_CONTEXT. CATCH CX_BOL_EXCEPTION. This is possible for any transaction context. . A custom tranaction context can be used for a further cycle. Create custom tx context DATA: my_tx_context TYPE REF TO cl_crm_bol_custom_tx_context. 6. lv_tx_ctxt TYPE REF TO if_bol_transaction_context. * 2. * 3. Custom transaction contexts are offered for collecting single BO transactions which belong logically together. If you don’t need the direct synchronization you can delay it by setting optional parameter IV_SUPPRESS_BUFFER_SYNC = ABAP_TRUE.. It might be that a newly created root object refers to another newly generated object. Add some single BO transactions DATA: lv_entity1 TYPE REF TO cl_crm_bol_entity.3 Collective transactions and Change tracking There is no monitoring of dependencies between root objects so far. Thus the event could be used for retrieving a followup transaction context.2 Excluding Entities from the Central Modify Normally all changed as well as created or deleted dependent objects are sent to the underlying APIs with one central call of the BOL core method MODIFY. So it may happen.5. In case of single BO transaction contexts the event parameter INSTANCE holds the name and key of the associated root entity. With release WEBCUIF 7.0 event parameter LOCKS_KEPT publishes the locking state of the BO after the end of the transaction. which is defined for each entity property and which may take one of the following public constants defined in the interface IF_GENIL_OBJ_ATTR_PROPERTIES: READ_ONLY CHANGEABLE NOT DEFINED HIDDEN MANDATORY TECHNICAL Use the entity method GET_PROPERTY_MODIFIER for access.5 Advanced Entity features 6. An entity was sent with MODIFY.5. but its attributes are still initial. Depending on the application this call may appear automatically at certain ‘sync points’.6. AFTER_TX_FINISHED Raised by single BO transaction contexts after TX_FINISHED event. The activation can also be propagated to aggregated children recursively via setting optional parameter IV_PROPAGATE_2_DEPENDENT. TX_FINISHED Raised by any transaction context when the transaction cycle has finished either via COMMIT or REVERT. By default it is always possible to change attributes of query services. Input readiness is determined from the so called Property Modifier. 6. At this time the raising context is already removed from the global transaction manager. which are not ready for sending and therefore cause errors. 6. See also section 6. An explicit change of the state is possible with the methods ACTIVATE_SENDING and DEACTIVATE_SENDING.1 Input Readiness and Entity Property Modifiers In order to check if an entity attribute is read only.4 Tracking transaction state In order to track the state of a certain transaction context several event are offered: LOCK_SET Raised only by single BO transaction context when the associated business object was locked. In the latter case the . you may use entity method IF_BOL_BO_PROPERTY_ACCESS~IS_PROPERTY_READONLY: It returns ABAP_TRUE in case the property is not changeable and not mandatory. An entity was explicitly deactivated for sending. that entities are sent.Business Object Layer (BOL) Programming Guide Page 31 6. In such cases it makes sense to exclude such entities from sending. Entities are automatically excluded from sending for the following reasons: A dependent entity was newly created. Beside the default value NO_PROPAGATION the values PROPAGATE_2_ALL and PROPAGATE_2_INACTIVE_ONLY are possible. but the changes have not been accepted by the underlying API and it has not been changed since. The current status of an entity can be checked with method IS_SEND_ACTIVE on the entity instance.4. 6. warningand error messages. Message Handling Model CL_CRM_BOL_CORE 1 1 CL_CRM_GENIL_MESS_CONT_MANAGER 1 * IF_GENIL_MESSAGE_CONTAINER Figure 32: The message container manager handles all message containers The message container manager can be reached via the BOL core. lv_object_id TYPE crmt_gnil_object_id. Thus deactivated sub-children might be preserved. * .... Messages are collected in so called ‘message containers’.. * or directly lv_mc = lv_bol_core->get_global_message_cont( ). lv_object_name = lv_order->get_name( ). to obtain the global message container DATA: lv_mc TYPE REF TO if_genil_message_container. * . Figure 33: Access the message container for a particular entity . lv_mc = lv_order->get_message_container( ). which are handled by the message container manager: There is one message container for each access object instance and a global one for all general messages without object relation.Business Object Layer (BOL) Programming Guide Page 32 recursion stops at child objects were sending is already activated. lv_object_id = lv_order->get_key( ). DATA: lv_mc TYPE REF TO if_genil_message_container. lv_mc = lv_mcm->get_message_cont( iv_object_name = lv_object_name iv_object_id = lv_object_id ). to obtain the object related message container DATA: lv_object_name TYPE crmt_ext_obj_name. lv_mcm = lv_bol_core->get_message_cont_manager( ).6 Business Error Handling The business object layer offers a message protocol to support communication of information-. The following coding example shows how to get access to a particular message container: * Access messages of a business object * Get message container manager DATA: lv_mcm TYPE REF TO cl_crm_genil_mess_cont_manager. lv_mc = lv_mcm->get_global_message_cont( ). see also section 5. see also section 5.Business Object Layer (BOL) Programming Guide Page 33 The message container interface IF_GENIL_MESSAGE_CONTAINER provides the method GET_MESSAGES for access. So only in exceptional situations an explicit synchronization between BOL buffer and GenIL component is necessary. Since it takes the message type as parameter. lt_error_messages = lv_mc->get_messages( lv_mc->mt_error ). when CL_CRM_BOL_CORE->MODIFY() is called. So it is in general possible to program mainly against the bOL core. is preserved. 6. The effected entities remain in buffer state modified. warnings and information.8 Buffering Issues It is very important to keep in mind that the business object layer operates on its own entity buffer. and Each entity modification as well as the creation or deletion of dependent entities is buffered. EXECUTE_ENTITY_METHOD Execute an entity method on a given set of enities. using the entities is more convenient. Method GET_NUMBER_OF_MESSAGES returns the number of messages of the specified type. However. it is possible to filter for errors. In this situation the application should present the error messages to the user and allow the correction of the input.5. * Access messages DATA: lv_number_of_errors TYPE int4. lt_error_messages TYPE crmt_genil_message_tab. In the CRM UIF application this happens automatically with each roundtrip.6. That means: Every entity found by a query. In this case the BOL will automatically switch off the sending to prevend the repeated sending of errors. even if wrong.5. lv_number_of_errors = lv_mc->get_number_of_messages( lv_mc->mt_error ). The following sections explain the possibilities . see also section 5. changes might be rejected by the underlying business logic in case of errors. and sending deactivated. Contrary the corresponding BOL core method takes in general a collection of entities as input. Thus the user input. The underlying buffers of the GenIL components (for the various business object types) are synchronized with BOL modifications.5. valid. Logically entity methods operate always on the entity instance they are called on. EXECUTE_ENTITY_METHOD2 Execute an entity method type 2 on a given set of enities. The difference in many cases is the possible amount of objects to execute the operation on. This may be used to give the user a hint that messages exist.6. Beside this multi object enabled operations the BOL core supports all major operation provided by the entities directly.2. Vice versa the BOL buffer is usually informed automatically about data changes in the GenIL component.5. IF lv_number_of_errors <> 0.7 Mass operations using the BOL core Many operation of the entity API could also be called via the BOL core instance. Every entity read via navigation following a relation. Possible values for the message types are defined as constants MT_ALL/MT_ERROR/MT_WARNING/MT_INFO/MT_SUCCESS in the message container interface.5. A further change of attributes will automatically activate sending again for the entity. ENDIF. 6. Figure 34: Check message count and retrieve messages from a message container As already mentioned in section 6. The following operations are supported as mass operation on a collection of entities: DELETE_ROOT_ENTITIES Delete a given set of root entities. If there is realy a synchronization issue. Note: For optimal system performance you should always use the default mode NORMAL. Such errors should always be investigated. Therefore the navigation methods GET_RELATED_ENTITY and GET_RELATED_ENTITIES take an optional parameter IV_MODE.8. it should be used very carefully to avoid performance problems. In some reason the underlying business logic does not allow buffering. which could be solved with bypassing the buffer it points mostlikly to an error.8. This model part has to be defined as a so called BOL View in the SAP implementation guide (View cluster GENIL_VIEWDEF).3 Preloading BOL Views The last two sections explained how to synchronize a single entity or relation. Being noncacheable is an unchangeable model property of a relation (IF_GENIL_OBJ_MODEL~ RELATION_IS_CACHEABLE). since this will be a global setting this should be desided very careful! 6. which may be set to one of the following constants (defined in class CL_CRM_BOL_ENTITY): NORMAL .8. Since this method calls the underlying application programming interface directly. BYPASSING_BUFFER: This reads the relation from the underlying API ignoring the buffer. This happens only if the parent relation of the entity is an invalid 1:N relation and there are less than 20 objects in the current relation. . In this case it should be incorporated in the model. Note: As a result of the synchronization the BOL may detect the deletion of an entity which will result in exception CX_BOL_EXCEPTION. BUFFER_ONLY: This takes the relation only from the buffer. if the buffer is invalid. Non-cacheable relations are always read from the underlying API. ignoring the given mode. 6.This is the default and means: Take relation from buffer and read it from the underlying API. The BOL may deside to turn a REREAD call into a GET_RELATED_ENTITIES call for buffer update efficiency reasons.Business Object Layer (BOL) Programming Guide Page 34 6. which are not subject to buffering. Even empty relations are buffered. In case the entity is in state created the method does nothing. In general we distinguish between cacheable relations and those. In case the entity is in state modified the attributes are not changed to preserve the changes. If a larger set of entities with relations should be synchronized these methods are too inefficient For that reason it is possible to load a well-defined part of the object model with a given start entity or set of entities at once.2 Entity Relations The relationship between entities is also subject of buffering. Like buffered properties the relations may become invalid and get synchronized automatically on the next access. However. For the cacheable relations a mode can be specified for navigation.1 Entity Properties The entity method CL_CRM_BOL_ENTITY->REREAD may be used to synchronize the buffer state of the attributes and property modifiers of a single entity. The latter is a property of the underlying object model. The related object types BTAdminH.Business Object Layer (BOL) Programming Guide Page 35 Figure 35: BOL views are defined in the SAP implementation guide Figure 36: Each BOL view is assigned to a specific BOL component set Figure 37: Each BOL view has a unique view root. . BTTextH. which is either a root object or access object: here BTOrder. … and their relations are specififed in a table. . Beside the explicite fetch via the BOL core it is also possible to apply a view directly to a search result of a query service. In a later release this may combined with the reset survival mode. Therefore the CL_CRM_BOL_ENTITY->LOCK method takes an optional parameter IV_REREAD. Now we try it again and the property modifiers have to be refreshed. In fact this becomes the default for simple and dynamic query services.9 BOL Reset Since the BOL buffer and the message services permanently collect but not release information the amount of data constantly grows with time. this synchronization takes always place! 6.3. for which the Reset Survival Mode has been turned on (see section 6. When the BOL reset procedure starts the BOL core raises event RESET_TRIGGERED and when the reset has finish event RESET_FINISHED. After the method has run it may also be advantageous to call the ABAP garbage collector explicitly to finally remove all the freed objects. On the other hand many query services return Query Result Object as aggregation of actual entities for performant result display.5 Buffering of Query results Since queries might return a big amount of objects they may increase considerably to the memory consumption of the bOL buffer.4 Locking with Synchronization After setting a lock it is sometimes necessary to synchronize the BOL buffer for the locked entities with the current database state for the following reasons: The entity could have been changed by someone else since the last read operation. On the down side of this the object instances are not longer unique. see section 6. The state could be checked via public attribute RESET_RUNNING of the BOL core instance. During the BOL reset most BOL API operation are not possible. Due to the failure the entity was set to read-only mode. or The last lock attempt failed. Adding the result to the central buffer has to be enforced by setting optional parameter IV_ADD_QRESOBJ_2_BOL_BUFFER of method GET_QUERY_RESULT to ABAP_TRUE.8). This mode does not preserve the actual entity instance. With release WEBCUIF this can be further leveraged by not adding them to the central BOL buffer. only the related object is remembered and a new entity instance is created for it. Note: With display mode support. In the CRM UIF application a BOL reset is triggered automatically from the framework whenever the user switches the workcenter with a click in the navigation bar. 6. This method clears all known buffers and messages. This applies also for entities contained in collections. because the entity was already locked.1. thus their lifetime is controlled by the application program. After the BOL reset all entity instances are useless: Further operations on them will cause runtime exceptions. which is either a BOL root object or access object. If it is set to ABAP_TRUE the full aggregation hierarchy of the locked root entity is invalidated in the buffer and synchronized on the next access. the model part defined by the view is read for each entity in the collection and stored in the buffer effectively. Because the BOL reset is the only way to clear the BOL buffer it is not so easy to control the memory consumption when frequent searches happen. 6. Without registration in the central buffer query result object instance live with result collection. In order to really keep the current entity instances you can provide an exception list when calling the RESET method.Business Object Layer (BOL) Programming Guide Page 36 Each BOL view is assigned to a specific component set and has a unique view root. Therefore a mechanism is necessary to get rid of all this buffered/collected data.8. Currently the only possibility is the BOL core reset using method CL_CRM_BOL_CORE->RESET. To do so you have to set the name of the view on the query service instance with method SET_VIEW_NAME. Per default it is set to ABAP_FALSE. Now the method PREFETCH_VIEW can be called on the BOL core: It takes the view name and a collection of view root entities as input.8. On the other hand any restore of data after the reset would be a waste of time in this case. There’s only one instance of it within one session and it cannot get lost or deleted. This leads also to the raise of the DELETED event for these entities.1 Core CL_CRM_BOL_CORE is the most important class of the BOL Application Programming Interface (API). Usage of local iterators does not. It is possible to add and remove objects referenced but not owned by the collection. It is possible to use the core services directly. which changes the global focus. The global transaction context logs all modifications automatically. Each instance corresponds to a distinct query object. Therefore this can be prevented by setting optional parameter IV_NO_RESTORE to ABAP_TRUE.5 Transaction Context The transaction context is represented by the interface IF_BOL_TRANSACTION_CONTEXT. all so far modified root object instances. Depending on the actual instance of the interface the scope of the represented transaction is a single root object instance. However. or any explicitly built subset in between. It stores query parameters but does not aggregate the query result. 7. during the reset procedure this must not interpreted as real deletion of the object! Since the BOL reset triggers also the reset of the loaded GenIL components it might also be necessary on session close in order to close connections to remote systems. Data access is done by help of the IF_BOL_BO_PROPERTY_ACCESS interface. . 7 Interface Classes Find below a summary of important classes and interfaces of the Business Object Layer (BOL). The BOL core aggregates the global transaction context.Business Object Layer (BOL) Programming Guide Page 37 During the BOL reset all entities get cleared from the buffer. query service or entity. Entities are centrally managed and cached. 7. 7. which includes all modified root objects. 7. 7. but it is recommended to use the more comfortable API classes – e.2 Query Services Generic query services are provided by the classes CL_CRM_BOL_QUERY_SERVICE and CL_CRM_BOL_DQUERY_SERVICE.g. Each instance is a unique representation for a specifc part of a business object.4 Collection A collection or list of generic objects represented by the interfaces IF_BOL_BO_COL and IF_BOL_ENTITY_COL and the underlying classes CL_CRM_BOL_BO_COL and CL_CRM_BOL_ENTITY_COL (among others). The BOL core is the central service provider for API classes and it communicates with the underlying business object implementation. A single BO transaction context can be accessed via the entity it belongs to.3 Entity The class CL_CRM_BOL_ENTITY is a generic representation for business object segments in the BOL. A collection provides global iteration. 8. GENIL_READ breaks in the read method of the GenIL core CL_CRM_GENERIC_IL_NEW and allows detailed investigations of the communication with the underlying GenIL component responsible for a specific Business Object. ID adjustments for new entities and buffer invalidation of changed entities. BOL_MODIFY_WATCH defines some important breakpoints. BOL_COLL_AUTOCLEAN activates the auto cleanup mode for all collections per default. If switched on. GENIL_SAVE allows investigations of the save process.2 Related checkpoint groups For detailed investigations and debugging it is often required to break in the generic interaction layer (GenIL). the merge back of data returned into the BOL buffer.1 BOL checkpoint groups The checkpoint group BOL_ASSERTS includes expensive checks for inner consistency and for the correct usage of the display mode. . 8. some checkpoint groups have been introduced. which can be used to track the data transport from the business object to the generic interaction layer (GenIL).0 and older. GENIL_MODEL_CHECKS activates consistency checks for the object models of the used GenIL components GENIL_LOCK makes the ABAP debugger stop when an entity is to be locked. which gives access to data persistency. Since this may lead to memory consumption issues this switch should only be used for testing purposes or to be compatible with framework versions SAP_ABA 7.Business Object Layer (BOL) Programming Guide Page 38 8 Checkpoint groups In order to highlight important places for debugging and to introduce expensive consistency checks. any attempt to change entities in display mode is detected. Checkpoint groups are activated with transaction SAAB (Assertions and Breakpoints) usually in the development environment. The checkpoint group GENIL_DC_CHECKS activates consistency checks for the data containers. GENIL_MODIFY breaks in the modify method of the GenIL core. This checkpoint group should be switched on in development and test systems to get early notice of problems related to the BOL usage. GENIL_GENERAL_CHECKS turns on general checks in the GenIL layer. An entity is a wrapper for a GenIL container object CL_CRM_GENIL_CONTAINER_OBJECT belonging to a data container. 9. and relations of an entity.Business Object Layer (BOL) Programming Guide Page 39 9 Inner Details and Debugging This section presents further aspects of the business object layer (BOL).1 BOL Entities BOL entities are managed by the BOL entity manager and use classes of the the Generic Interaction Layer (GenIL) to hold their data. This object is referred as CONTAINER_PROXY and holds the attributes. The manager entry includes values like the invalid and delta flags.g. Each entity holds a reference to its manager entry.. CL_CRM_BOL_CORE->MODIFY. The UML diagrams below show the connection between the classes involved and their main attributes.n CL_CRM_BOL_ENTITY my_manager_entry parent 1 #container_proxy 1 CL_CRM_GENIL_CONTAINER_OBJECT data_ref All entities are managed by the entity manager: It assures the uniqueness of entities and buffers access. Holding these values in the ENTITY_TAB of the entity manager enables efficient BOL table operations on all entities – e. CL_CRM_BOL_ENTITY_MANAGER entity_tab 1 0. properties. . 2 Collections Various collections reference a set of BOL entities and offer convenient access to their properties..n CL_CRM_BOL_QUERY_SERVICE CL_CRM_BOL_ENTITY A collection is represented by the IF_BOL_BO_COL interface and can either be an entity collection CL_CRM_ENTITY_COL or the generalized business object collection CL_CRM_BOL_BO_COL. <<Interface>> IF_BOL_BO_COL CL_CRM_BOL_BO_COL entity_list 1 CL_CRM_ENTITY_COL entity_list 1 0. GET_PROPERTY_AS_STRING or SET_PROPERTY. . A BO collection can hold entities (CL_CRM_BOL_ENTITY) and query services (CL_CRM_BOL_QUERY_SERVICE).. The access to properties of BOL objects is offered by the interface IF_BOL_BO_PROPERTY_ACCESS with its standard access methods like IF_BOL_BO_PROPERTY_ACCESS~GET_PROPERTY.n <<Interface>> IF_BOL_BO_PROPERTY_ACCESS 0.Business Object Layer (BOL) Programming Guide Page 40 9.