Professional Documents
Culture Documents
SAP AG Dietmar-Hopp-Allee 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20 www.sap.com
Copyright 2007 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix, i5/OS, POWER, POWER5, OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. SAP Library document classification: PUBLIC UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MaxDB is a trademark of MySQL AB, Sweden. Any Java Source Code delivered with this product is only to be used by SAPs Support Services and may not be modified or altered in any way. Documentation in the SAP Service Marketplace You can find this documentation at the following address:
http://service.sap.com/
SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.
Disclaimer Some components of this product are based on Java. Any code change in these components may cause unpredictable and severe malfunctions and is therefore expressively prohibited, as is any decompilation of these components.
(hereinafter: Customer) a) Subject Matter of the Agreement A) SAP grants Customer a non-exclusive, non-transferrable, royalty-free license to use the STLport.org C++ library (STLport) and its documentation without fee. B) By downloading, using, or copying STLport or any portion thereof Customer agrees to abide by the intellectual property laws, and to all of the terms and conditions of this Agreement. C) The Customer may distribute binaries compiled with STLport (whether original or modified) without any royalties or restrictions. D) Customer shall maintain the following copyright and permissions notices on STLport sources and its documentation unchanged: Copyright 2001 SAP AG E) The Customer may distribute original or modified STLport sources, provided that: o The conditions indicated in the above permissions notice are met; o The following copyright notices are retained when present, and conditions provided in accompanying permission notices are met: Copyright 1994 Hewlett-Packard Company Copyright 1996,97 Silicon Graphics Computer Systems Inc. Copyright 1997 Moscow Center for SPARC Technology. Copyright 1999,2000 Boris Fomitchev Copyright 2001 SAP AG Permission to use, copy, modify, distribute and sell this software and its documentation for any purposes is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Hewlett-Packard Company makes no representations about the suitability of this software for any purpose. It is provided as is without express or implied warranty.
Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Silicon Graphics makes no representations about the suitability of this software for any purpose. It is provided as is without express or implied warranty. Permission to use, copy, modify, distribute and sell this software and its documentation for any purposes is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Moscow Center for SPARC makes no representations about the suitability of this software for any purpose. It is provided as is without express or implied warranty. Boris Fomitchev makes no representations about the suitability of this software for any purpose. This material is provided "as is", with absolutely no warranty expressed or implied. Any use is at your own risk. Permission to use or copy this software for any purpose is hereby granted without fee, provided the above notices are retained on all copies. Permission to modify the code and to distribute modified code is granted, provided the above notices are retained, and a notice that the code was modified is included with the above copyright notice. Permission to use, copy, modify, distribute and sell this software and its documentation for any purposes is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. SAP makes no representations about the suitability of this software for any purpose. It is provided with a
limited warranty and liability as set forth in the License Agreement distributed with this copy. SAP offers this liability and warranty obligations only towards its customers and only referring to its modifications. b) Support and Maintenance SAP does not provide software maintenance for the STLport. Software maintenance of the STLport therefore shall be not included. All other services shall be charged according to the rates for services quoted in the SAP List of Prices and Conditions and shall be subject to a separate contract. c) Exclusion of warranty As the STLport is transferred to the Customer on a loan basis and free of charge, SAP cannot guarantee that the STLport is error-free, without material defects or suitable for a specific application under third-party rights. Technical data, sales brochures, advertising text and quality descriptions produced by SAP do not indicate any assurance of particular attributes. d) Limited Liability A) Irrespective of the legal reasons, SAP shall only be liable for damage, including unauthorized operation, if this (i) can be compensated under the Product Liability Act or (ii) if caused due to gross negligence or intent by SAP or (iii) if based on the failure of a guaranteed attribute. B) If SAP is liable for gross negligence or intent caused by employees who are neither agents or managerial employees of SAP, the total liability for such damage and a maximum limit on the scope of any such damage shall depend on the extent to which its occurrence ought to have anticipated by SAP when concluding the contract, due to the circumstances known to it at that point in time representing a typical transfer of the software. C) In the case of Art. 4.2 above, SAP shall not be liable for indirect damage, consequential damage caused by a defect or lost profit.
D) SAP and the Customer agree that the typical foreseeable extent of damage shall under no circumstances exceed EUR 5,000. E) The Customer shall take adequate measures for the protection of data and programs, in particular by making backup copies at the minimum intervals recommended by SAP. SAP shall not be liable for the loss of data and its recovery, notwithstanding the other limitations of the present Art. 4 if this loss could have been avoided by observing this obligation.
F) The exclusion or the limitation of claims in accordance with the present Art. 4 includes claims against employees or agents of SAP. 4. Adobe Document Services Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and / or other countries. For information on Third Party software delivered with Adobe document services and Adobe LiveCycle Designer, see SAP Note 854621.
Typographic Conventions
Type Style Example Text Description Words or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options. Cross-references to other documentation Example text Emphasized words or phrases in body text, graphic titles, and table titles Technical names of system objects. These include report names, program names, transaction codes, table names, and key concepts of a programming language when they are surrounded by body text, for example, SELECT and INCLUDE. Output on the screen. This includes file and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools. Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation. Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system. Keys on the keyboard, for example, F2 or ENTER.
Icons
Icon Meaning Caution Example Note Recommendation Syntax
EXAMPLE TEXT
Additional icons are used in SAP Library documentation to help you identify different types of information at a glance. For more information, see Help on Help General Information Classes and Information Classes for Business Information Warehouse on the first page of any version of SAP Library.
Example text
Example text
<Example text>
EXAMPLE TEXT
Contents
1 Business Object Layer .......................................................................8
1.1 Abstract................................................................................................... 8
1.1.2 Introduction .............................................................................................................. 8 1.1.3 Overview.................................................................................................................. 8 1.1.4 Basic Features of the BOL API ............................................................................... 10 1.1.4.1 Setting up a BOL Instance ................................................................................... 10 1.1.5 Advanced Features of the BOL API ........................................................................ 18 1.1.6 Interface Classes.................................................................................................... 29 1.1.7 Checkpoint Groups................................................................................................. 29
<July 2008>
1.1.2 Introduction
Using the BOL and its uniform application programming interface (API) to access business data offers considerable advantages compared to the various APIs typically available for business objects: The object-oriented BOL API is simple, uniform, and easy to use. The built-in buffer accelerates your applications. You can isolate your programs from any interface changes in the underlying business object-specific APIs. Development of SAP Customer Relationship Management (SAP CRM) applications is easy since the BOL has been designed to work hand-in-hand with the UI parts of the CRM WebClient UI framework. It is possible to enhance the BOL 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.
1.1.3 Overview
The BOL API consists of various interfaces and classes that you can use to access business data: CL_CRM_BOL_QUERY_SERVICE You use this class to select business objects. CL_CRM_BOL_ENTITY You use this class for implementing business objects. IF_BOL_TRANSACTION_CONTEXT You use this interface to control transaction behavior. IF_BOL_BO_COL You use this interface to provide collections to hold business objects. The lifetime of these objects lasts the entire session. The BOL API, however, provides you with the ability to free used business objects and their memory.
<July 2008>
Important objects in the BOL Programming ABAP and their corresponding interfaces and classes:
Objects
1..* Object Model 1 Transaction Context 1..*
1 1 BOL Core 1 *
1..* Entity *
Query Service
0..n
1
CL_CRM_BOL_CORE get_instance()
1
CL_CRM_BOL_ENTITY
0..n
CL_CRM_BOL_ENTITY_FACTORY
0..n
<<Interface>> IF_BOL_BO_COL CL_CRM_BOL_QUERY_SERVICE get_instance()
<July 2008>
10
<July 2008>
lv_obj_model_ type ref to cl_crm_genil_obj_model, lt_components_loaded type genil_component_tab. lv_obj_model = cl_crm_genil_model_service=>get_runtime_model( ). lv_obj_model_ ?= lv_obj_model. lt_components_loaded = lv_obj_model_>get_components_loaded( ).
<July 2008>
11
* Set a search criterion lv_query->set_property( iv_attr_name = City iv_value * Read a search criterion DATA: lv_city type string. lv_city = lv_query->get_property_as_string( City ). = Walldorf ).
* Execute query and receive result DATA: lv_result TYPE REF TO if_bol_entity_col. lv_result = lv_query->get_query_result( ). If you already know the name of the query service to be used, there is no need to use the model: you can directly access the query service by name. As you can see in the above example, it is also possible to retrieve search criteria from the query service. You can perform queries and other methods of the BOL API using the BOL Browser (transaction GENIL_BOL_BROWSER): 1. Select the desired component set, for example, SAMPLE. 2. Select the query object and enter the parameters before you select Find. 3. Double click an object ID displayed in the List Browser to see a particular object with its attributes.
* Set general query parameter for maximum number of hits DATA: lt_params type crmt_name_value_pair_tab,
12
<July 2008>
ls_params type crmt_name_value_pair. ls_params-name = 'MAX_HITS' . ls_params-value = '5'. APPEND ls_params TO lt_params. lv_advanced_query->set_query_parameters( it_parameters = lt_params ).
* Add selection criteria: Ordernumber > 5 lv_advanced_query->add_selection_param( iv_attr_name = 'ORDER_NUMBER' iv_sign iv_option iv_low iv_high = 'I' = 'GT' = '5' = '' ). Greater than
* Execute the query and receive result DATA: lv_result type ref to if_bol_entity_col. lv_result = lv_advanced_query->get_query_result( ). To display advanced queries in the CRM WebClient UI, easy-to-use tags have been developed. Query templates are used to store and retrieve saved searches with predefined search criteria: Syntax * Save query as template lv_advanced_query->save_query_as_template( iv_query_id = My Query iv_overwrite = abap_true ).
<July 2008>
13
lv_iterator = lv_result->get_iterator. DATA: lv_entity TYPE REF TO cl_crm_bol_entity. lv_entity = lv_iterator->get_first( ). Entity is business partner here WHILE lv_entity IS BOUND.
Access attributes of business objects selected DATA: lv_firstname TYPE string, lv_lastname TYPE string.
Get a list of 1:N related entities DATA: lv_addresses TYPE REF TO if_bol_entity_col. lv_addresses = lv_entity->get_related_entities( Addresses ).
* lv_entity = lv_iterator->get_next( ). ENDWHILE. The last section of code shows how to navigate from one entity to a related entity. Use the BOL Object Model Service or the Model Browser to find out which relationships have been defined in the model for a particular object type.
1.1.4.6 Transactions
One of the most important aspects of BOL programming is to know how to modify data. You can create, modify, and delete entities in accordance with the BOL transaction model, which supports several kinds of transaction contexts to handle entity operations consistently. The global transaction context holds all modified root entities, whereas the fine granular transaction context exists for each root object instance. The custom transaction context can be used to handle special situations, where more than one (but not all) modified object forms the transaction. This section discusses only the global context. For more information about the fine granular transaction context, see Fine Granular Transaction Handling [page 24].
14
<July 2008>
DATA: lt_params TYPE crmt_name_value_pair_tab, ls_params TYPE crmt_name_value_pair. ls_params-name = PROCESS_TYPE. ls_params-value = TA. APPEND ls_params TO lt_params.
* 2. Get factory for business object DATA: lv_order_factory TYPE REF TO cl_crm_bol_entity_factory. lv_order_factory = lv_bol_core->get_entity_factory( BTOrder ).
* 3. Create root entity DATA: lv_order TYPE REF TO cl_crm_bol_entity. lv_order = lv_order_factory->create( lt_params ).
* 4. Create child objects DATA: lv_order_header TYPE REF TO cl_crm_bol_entity, lv_activity_header TYPE REF TO cl_crm_bol_entity. lv_order_header = lv_order->create_related_entity( BTOrderHeader ). lv_activity_header = lv_order_header->create_related_entity( BTHeaderActivityExt ).
* 5. Submit child objects created lv_bol_core->modify( ). * 6. Save and commit changes using global transaction context DATA: lv_transaction TYPE REF TO if_bol_transaction_context lv_transaction = lv_bol_core->get_transaction( ). lv_transaction->save( ). lv_transaction->commit( ). You can distinguish between the creation of root objects using the factory and the creation of dependent or child objects using method CREATE_RELATED_ENTITY. The first case directly triggers a call to the underlying API, whereas in the second case it does not. In the second case, it is necessary to trigger the API call explicitly by calling the MODIFY method, which sends the changes to the underlying GenIL. Without this call, the created child objects are not saved.
<July 2008>
15
The current locking granularity of the BOL is the root object instances, so the lock request for an entity is always delegated to the corresponding root instance. The following code shows how to lock an entity: Syntax * Lock BOL entity DATA: lv_success TYPE crmt_boolean. lv_success = lv_entity->lock( ). If the lock was set, the return value LV_SUCCESS is true (ABAP_TRUE or IF_GENIL_BOOLEAN => TRUE ).
lv_order_header ).
* 4. save and commit your changes lv_transaction->save( ). lv_transaction->commit( ). The given example works with or without display mode support, since the lock is explicitly set.
16
<July 2008>
For root object instances, the DELETE method call is sent directly to the API where the complete aggregation hierarchy is deleted. The deletion is written to the database with an internal COMMIT WORK. Syntax * Delete root entity lv_order->delete( ). In the case of a child object, the deletion is not automatically sent to the API. You have to trigger this explicitly by calling the MODIFY method of the BOL core. Syntax * Delete child object lv_order_header->delete( ). lv_bol_core->modify( ).
DATA: lv_transaction TYPE REF TO if_bol_transaction_context. lv_transaction = lv_bol_core->get_transaction( ). lv_transaction->save( ). lv_transaction->commit( ). Note: You must save and commit the transaction to confirm the deletion. Immediately after CL_CRM_BOL_CORE->MODIFY has been executed, the entity is deleted in the BOL buffer. This is published in the entity instance by creating a DELETED event. After the deletion, any further access to the entity instance can lead to a CX_BOL_EXCEPTION exception.
lv_result TYPE REF TO if_bol_entity_col. ls_param-name = PROCESS_TYPE. ls_param-value = TSRV. append ls_param to lt_param. TRY.
<July 2008>
17
lv_result = lv_order_header->execute( iv_method_name = createFollowUp it_param * Error handling CATCH CX_CRM_BOL_METH_EXEC_FAILED. * * An exception is received if method has indicated an error and has not returned more than one entity. ... ENDTRY. = lt_param ).
* Execute query and access entity DATA: lv_entity type ref to cl_crm_bol_entity. lv_entity = ... mode -Entity is in now display
* Switch to change mode and change entity lv_entity->switch_to_change_mode( ). Reread and lock entity
18
<July 2008>
iv_value ENDIF.
= New Value ).
When an entity is locked, its properties are re-read to ensure that the most current data is available.
<<interface>> IF_BOL_BO_PROPERTY_ACCESS
CL_CRM_BOL_QUERY_SERVICE
CL_CRM_BOL_ENTITY
The interface offers a standard means to work with BOL objects. Note that it is possible to have an instance of IF_BOL_BO_PROPERTY_ACCESS for any BOL object. Syntax * Get search criterion of BOL query DATA: lv_query TYPE REF TO cl_crm_bol_query_service, lv_city_type string. lv_query = cl_crm_bol_query_service=>get_instance( QUERY_NAME ). lv_city = lv_query->if_bol_bo_property_access~get_property_as_string( City ). Short form using alias lv_city = lv_query->get_property_as_string( City ).
* 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 ). Short form using alias lv_entity->set_property( iv_attr_name = CITY iv_value = Walldorf ).
<July 2008>
19
* Cast to property_access interface DATA: lv_business_object TYPE REF TO if_bol_bo_property_access. lv_business_object ?= lv_entity. In addition to 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. Syntax * Get key code DATA: lv_person TYPE REF TO cl_crm_bol_entity, lv_sex type bu_sexid. Defines values 1 = Female, 2 = Male ... lv_sex = lv_person->get_property( SEX ). Key code
* Get property text for key code: * -> Male or Female translated in current language DATA: lv_sex_text type string. lv_sex_text = lv_person->get_property_text( SEX ). The text is taken from the domain values if available or is determined by the underlying GenIL component.
IF_BOL_BO_COL
CL_CRM_BOL_BO_COL
IF_BOL_ENTITY_COL
CL_CRM_BOL_ENTITY_COL
The collection interfaces offer a number of methods to work with collections, such as INSERT, GET_FIRST, GET_NEXT, GET_CURRENT, SORT, CLEAR, MARK, and UNMARK.
20
<July 2008>
If you want to iterate on the collection without moving the focus (and without triggering timeconsuming follow-up processes) you can use local iteration. To do so, request an iterator object from the collection and use this to iterate. Syntax * Create collection DATA: lv_collection TYPE REF TO cl_crm_bol_bo_collection, lv_property_access TYPE REF TO if_bol_bo_property_access, lv_query TYPE REF TO cl_crm_bol_query_service. CREATE OBJECT lv_collection. ... * Add item and make it current lv_collection->if_bol_bo_col~insert( iv_bo Iv_index = lv_query = 1
Iv_set_focus = ABAP_BOOL ). * Global iteration lv_property_access = lv_collection->get_next( ). Global iteration * Local iteration DATA: lv_iterator TYPE REF TO if_bol_bo_col_iterator. lv_iterator = lv_collection->get_iterator( ). lv_property_access = lv_iterator->get_first( ) WHILE lv_query_is_bound. lv_property_access = lv_collection->get_next(). Local iteration does not ENDWHILE. move focus moves focus
1.1.5.3.2 Searching
The collections provide the method FIND to search for a given business object in the collection. If the business object is found, it is returned and the focus is set to this collection entry. You can search by index, business object instance, or object name and ID, but only one of these parameters is used for the search at a time. The parameters are taken in the given sequence. For example, if you provide an index and an instance, only the index is used. The local iterator interface supports the search for a single property. This is provided by the method FIND_BY_PROPERTY. The first object, whose property has the given value, is returned. Neither the global nor the local collection pointer is influenced by this operation. Syntax * Find by property DATA: lv_persons lv_male TYPE REF TO cl_crm_bol_entity_collection,
<July 2008>
21
lv_iterator = lv_persons->get_iterator( ). lv_male = lv_iterator->find_by_property( iv_attr_name = SEX iv_value * Set collection focus on the entity found lv_persons->find( iv_bo = lv_male ). = 2 ).
1.1.5.3.3 Sorting
Collections can be sorted with the SORT method and stay in the resulting sort order. Note You can not undo the sorting process. The mandatory parameter IV_ATTR_NAME specifies the property that the collection is sorted for. If you do not specify IV_SORT_ORDER, the sort order defaults as ascending. Syntax * Sorting DATA: lv_persons lv_male TYPE REF TO cl_crm_bol_entity_collection, TYPE REF TO cl_crm_bol_entity,
lv_iterator TYPE REF TO if_bol_bo_col_iterator. lv_persons->sort( iv_attr_name = SEX iv_sort_order = IF_BOL_BO_COL=>SORT_DESCENDING ). The sorting is alphabetical and based on the string representation of the property. Since this can lead to false results (for example, when working with dates) it is possible to control the sorting by providing an instance of IF_BOL_COL_SORTING. During the sort process, the method IS_A_GREATER_B is called whenever two values are compared. To modify the sort order as needed, implement this method and provide the interface.
22
<July 2008>
The selected element is implicitly set with the following methods: Method IF_BOL_BO_COL~GET_NEXT IF_BOL_BO_COL~GET_PREVIOUS Note In single selection mode, the current or focus element is always defined, except when the collection is empty. The methods of the interface IF_BOL_BO_COL_MULTI_SEL are deactivated. When multi selection mode has been activated, you may use the methods of the interface IF_BOL_BO_COL_MULTI_SEL to mark and unmark entries, and to check which entries have been marked (IF_BOL_BO_COL_MULTI_SEL~MARK, UNMARK, GET_MARKED). In multi selection mode, the collection methods behave differently than in single selection mode: Method 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 Result Returns the last selected element Returns the index of the last selected element Does nothing Finds, eventually selects and returns an element Does nothing Does nothing Result Moves focus to the next element and returns it Moves focus to the previous element and returns it
<July 2008>
23
Some collections need to protect their content, especially if they are essential for the further operation of the application. You can use method IF_BOL_BO_COL~SET_RESET_SURVIVAL_MODE to indicate that the root and access entities are to be recreated after the BOL reset. To receive notice at runtime of any collections that are not reset-compliant because they contain dependent entities, you can activate the assertion group BOL_ASSERTS using transaction SAAB (assertions, breakpoints and logpoints).
* 2. Add some single object transactions DATA: lv_entity1 TYPE REF TO cl_crm_bol_entity, lv_entity2 TYPE REF TO cl_crm_bol_entity, lv_tx_ctxt TYPE REF TO if_bol_transaction_context. ... lv_tx_ctxt = lv_entity1->get_transaction( ). my_tx_context->add_tx_context( lv_tx_ctxt ). lv_tx_ctxt = lv_entity2->get_transaction( ). my_tx_context->add_tx_context( lv_tx_ctxt ).
* 3. Save and commit both single object transactions together my_tx_context->save( ). my_tx_context->commit( ). Transaction contexts can be requested at any time by using method IF_BOL_TRANSACTION_CONTEXT~CHECK_SAVE_NEEDED. This allows you to see if data has been changed or if a save is necessary.
24
<July 2008>
To check if an entity property is read only, you can use method IF_BOL_BO_PROPERTY_ACCESS~IS_PROPERTY_READONLY. It returns ABAP_TRUE if the property is not changeable and not mandatory. The property modifier is defined for each entity property and calculates input readiness. It takes one of the following public constants defined in the interface IF_GENIL_OBJ_ATTR_PROPERTIES: READ_ONLY CHANGEABLE NOT DEFINED HIDDEN MANDATORY TECHNICAL To access the property modifier, use the entity method GET_PROPERTY_MODIFIER. By default, it is possible to change properties of query services.
<July 2008>
25
The message container manager can be reached using the core. The following code shows how to access a particular message container: Syntax * Access messages of a business object
* 1) Use the message container manager DATA: lv_mcm TYPE REF TO cl_crm_genil_mess_cont_manager. lv_mcm = lv_bol_core->get_message_cont_manager( ).
* 2) ... to obtain the message container DATA: lv_object_name TYPE crmt_ext_obj_name, Lv_object_id TYPE crmt_gnil_object_id.
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 ).
The message container interface provides the method IF_GENIL_MESSAGE_CONTAINER~GET_MESSAGES for access. Since it takes the message type as parameter, it is possible to filter for errors, warnings, and information. Possible values for the message types are defined as constants MT_ALL, MT_ERROR, MT_WARNING, MT_INFO, and MT_SUCCESS in the IF_GENIL_MESSAGE_CONTAINER interface.
26
<July 2008>
The method GET_NUMBER_OF_MESSAGES returns the number of messages of the specified type. This can be used to notify a user of new messages.
Syntax * 3) Access messages DATA: lv_number_of_errors TYPE int4, lt_error_messages TYPE crmt_genil_message_tab. lv_number_of_errors = lv_mc->get_number_of_messages( lv_mc->mt_error ). IF lv_number_of_errors <> 0. lt_error_messages = lv_mc->get_messages( lv_mc->mt_error ). ENDIF.
<July 2008>
27
This only reads the relationship from the BOL buffer. BYPASSING_BUFFER This only reads the relationship from the underlying API, ignoring the BOL buffer. Non-cacheable relations are read from the underlying API for each navigation, ignoring the given mode. Being non-cacheable is an unchangeable model property of a relationship (IF_GENIL_OBJ_MODEL~ RELATION_IS_CACHEABLE).
28
<July 2008>
1.1.6.3 Entities
The class CL_CRM_BOL_ENTITY is a generic representation for business objects in the BOL. Each instance is a unique representation for a specific business object. You can access data using the IF_BOL_BO_PROPERTY_ACCESS interface. Entities are centrally managed and cached.
<July 2008>
29
change entities in display mode is detected. You can activate this checkpoint group in development and test systems to get early notice of problems related to the BOL usage. BOL_MODIFY_WATCH This checkpoint group defines important break points, which can be used to track the data transport from the business object to the Generic Interaction Layer (GenIL), the merge back of data returned into the BOL buffer, ID adjustments for new entities, and buffer invalidation of changed entities. BOL_COLL_AUTOCLEAN This checkpoint group activates the auto cleanup mode for collections as default. This may lead to memory problems, so it should only be used for testing purposes or compatiblility purposes with framework versions SAP CRM 5.0 and older.
30
<July 2008>
CL_CRM_BOL_ENTITY_MANAGER entity_tab
1 data_ref
#container_proxy
CL_CRM_GENIL_CONTAINER_OBJECT
In the diagram above: All entities are managed by the entity manager. It assures the uniqueness of entities and buffer access. Each entity holds a reference to its manager entry. The manager entry includes values such as the invalid and delta flags. Holding these values in the ENTITY_TAB of the entity manager enables efficient BOL table operations for all entities, for example, CL_CRM_BOL_CORE->MODIFY(). An entity is a wrapper for a GenIL container object CL_CRM_GENIL_CONTAINER_OBJECT belonging to a data container. This object is referred to as CONTAINER_PROXY and holds the attributes, properties, and relationships of the entity.
1.2.2 Collections
Various collections reference a set of BOL entities and offer convenient access to their properties.
<July 2008>
31
<<Interface>> IF_BOL_BO_COL
CL_CRM_BOL_BO_COL entity_list 1
CL_CRM_ENTITY_COL entity_list 1
In the diagram above: 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. A business object collection can hold entities (for example, CL_CRM_BOL_ENTITY) and query services (for example, CL_CRM_BOL_QUERY_SERVICE). Access to properties of BOL objects is offered by the interface IF_BOL_BO_PROPERTY_ACCESS with its standard access methods, such as IF_BOL_BO_PROPERTY_ACCESS~GET_PROPERTY, GET_PROPERTY_AS_STRING(), or SET_PROPERTY().
32
<July 2008>
-collection_wrapper
In the above diagram: Each context node represented by an instance derived from class CL_BSP_WD_CONTEXT_NODE has a collection wrapper. Wrappers implemented by class CL_BSP_WD_COLLECTION_WRAPPER can be shared among different context nodes. The collection wrapper wraps a business object collection, IF_BOL_BO_COL, which can be set (CL_BSP_WD_COLLECTION_WRAPPER->SET_COLLECTION) and cleared (SET_COLLECTION) but not directly accessed. The collection wrapper implements the business object collection interface to provide indirect access to the wrapped collection. The attributes of the current entity in the collection (wrapper) are displayed on the UI.
<July 2008>
33
The IF_BOL_ENTITY_COL~FOCUS_CHANGED event of the collection is published by the wrapper as a NEW_FOCUS event. This allows implementing dependencies between model nodes, for example, when the user selects another order entity on the screen and the list of order items displayed is adjusted accordingly. A context node is called Model Node if it holds BOL entities defined in a GenIL component.
CL_BSP_WD_CONTROLLER
+owner
+typed_context
CL_BSP_WD_CONTEXT
+<name>
1..n
CL_BSP_WD_CONTEXT_NODE
In the above diagram: Each view, custom, or component controller owns a context that it inherits from CL_BSP_WD_CONTEXT, which holds a set of context nodes derived from CL_BSP_WD_CONTEXT_NODE. You can create the context within the WD_CREATE_CONTEXT method of the specific controller, which overrides the base class method provided by CL_BSP_WD_CONTROLLER. In the construction of the context, all of its nodes are created. By overriding the WD_INIT_CONTEXT method (also provided by CL_BSP_WD_CONTROLLER) a specific controller can explicitly initialize its context nodes.
34
<July 2008>
Neither context nor context nodes are expected to be shared between controllers. The underlying collections can be shared using the collection wrapper class by context node binding.
+view 1
<VIEW>
+controller
+<name>
1..n
1 +typed_context
CL_BSP_WD_CONTEXT
In the above diagram: The view (derived from CL_BSP_PAGE) is created and owned by the controller. Context nodes can be set as page attributes to a view (done in the controllers implementation of the CL_BSP_WD_VIEW_CONTROLLER->SET_MODELS() method). These page attributes are used for data binding to show model attributes on the view or page. The context nodes belonging to a controller are also kept in the controllers table M_MODELS, inherited from base class CL_BSP_CONTROLLER2. This information is used for data binding in the DO_HANDLE_DATA() method.
<July 2008>
35
Sometimes it is necessary to display further entity-related attributes that are not part of the underlying GenIL model and that are calculated at runtime. This is possible using mixed node elements, which contain a regular BOL entity plus a value part with application-defined attributes. The corresponding context node is referred to as a mixed node. A mixed node element (represented by class CL_BSP_WD_MIXED_NODE) consists of a model part referencing a regular BOL entity and a value part holding additional application-defined data. CL_BSP_WD_MIXED_NODE implements the IF_BOL_BO_PROPERTY_ACCESS interface and does not inherit from CL_BSP_WD_CONTEXT_NODE. When creating the element you hand over the BOL entity reference and a structure with application-defined data. You use the IF_BOL_BO_PROPERTY_ACCESS interface to access the elements properties. The mixed node automatically dispatches the request to either the model or the value part. You may also use <IF_BSP_WD_EXT_PROPERTY_ACCESS>~GET_MODEL_NODE() to access the underlying BOL entity. Mixed node elements can be added to IF_BOL_BO_COL collections, which accept objects implementing the IF_BOL_BO_PROPERTY_ACCESS interface. It is easy to display mixed nodes on the UI, as context node binding proceeds as normal. To facilitate the application of mixed node elements, a specialization of the collection wrapper CL_BSP WD_2COLLECTION_WRAPPER is available. Assign CL_BSP_WD_2COLLECTION_WRAPPER to your mixed context node and use its SET_VALUE_STRUCT method to declare the data structure with additional application-defined attributes. Add BOL entities to the nodes collection wrapper as usual. When its items are accessed (for example, for UI display) a mixed node element with application-defined attributes is automatically created and returned. This technique saves memory because you only create the value part if it is needed. The collection wrapper supports sorting by both model and value attributes. CL_BSP WD_2COLLECTION_WRAPPER uses the built-in unifier manager, as shown in the diagram below:
36
<July 2008>
CL_BSP_WD_COLLECTION_WRAPPER
LCL_UNIFIER_MANAGER
(from CL_BSP_WD_2COLLECTION_WRAPPER)
<<Interface>> IF_BOL_BO_PROPERTY_ACCESS 1
<<Interface>> IF_BOL_BO_PROPERTY_ACCESS
CL_BSP_WD_VALUE_NODE
The CRM WebClient UI framework also supports value nodes, which contain value node elements having an application-defined value part only. A value node element is represented by class CL_BSP_WD_VALUE_NODE, which accepts application-defined attributes in its constructor method. You can use the IF_BOL_BO_PROPERTY_ACCESS interface to access its attributes. Value node elements can be added to IF_BOL_BO_COL collections. Context node binding and the UI display work as normal.
<July 2008>
37