Most of the functionality provided by the ABAP Extension Module occurs inside of the SAP application. For most of the virtual functions that every connector must implement, there is a corresponding ABAP function module in the SAP application. However, SAP does not provide ABAP function modules that support the specific requirements of the init(), doVerbFor(), and pollForEvents() methods, so these function modules have been developed and delivered as part of the connector module. While the Java components provide some functionality, the majority of the processing for these methods is done by the ABAP components in the SAP application.
Table 5 shows the virtual Java methods that the connector module
implements and their corresponding ABAP components. Keep in mind that
this table does not provide a complete list of the ABAP components used by the
connector.
Table 5. Java components and their corresponding ABAP components
Java components | ABAP components |
---|---|
doVerbFor() | Y_XR_RFC_DO_VERB_NEXTGEN |
getVersion() | No implementation required |
getBOHandlerForBO | No implementation required |
init() | Y_XR_RFC_LOGON |
pollForEvents() | Y_XR_RFC_EVENT_REQUEST Y_XR_RFC_EVENT_RETURN |
terminate() | No implementation required |
Together, these ABAP function modules are the core of the ABAP Extension Module. The following sections describe connector initialization, business object processing, and how the connector handles event notification.
The implemented functions are discussed in the rest of this chapter.
The init() method calls the ABAP function module Y_XR_RFC_LOGON to validate that the destination SAP application is running and that the RFC library can be used to execute ABAP function modules. If the function module does not execute successfully, the connector terminates.
All service call requests for SAP are initiated by the doVerbFor() method in the Java component of the connector module. The connector's ABAP function module Y_XR_RFC_DO_VERB_NEXTGEN and an ABAP handler in the ABAP component of the connector module handle the requests.
Figure 5 illustrates business object processing.
Figure 5. Business object processing of doVerbFor()
In the Java component of the connector module, the doVerbFor() method of a single business object handler implementation handles all of the business object requests from the integration broker and all business object events from the pollForEvents() method. In either case, doVerbFor() executes in the following manner:
The doVerbFor() method passes business object data to function module Y_XR_RFC_DO_VERB_NEXTGEN and then creates an entirely new business object structure from the returned business object data.
In the ABAP component of the connector module, the connector's ABAP function module Y_XR_RFC_DO_VERB_NEXTGEN is responsible for handling all WebSphere business object processing in the SAP application. Specifically, it routes business object data to the appropriate ABAP handler. In this sense, function module Y_XR_RFC_DO_VERB_NEXTGEN can be thought of as a business object router. It always executes in the following manner:
Y_XR_RFC_DO_VERB_NEXTGEN uses ABAP handlers to fulfill each object type and verb-specific request. Y_XR_RFC_DO_VERB_NEXTGEN uses the value in a business object's verb application-specific information to determine which ABAP handler to call. Y_XR_RFC_DO_VERB_NEXTGEN can be thought of as a router from the doVerbFor() method to an ABAP handler.
ABAP handlers are unique to the connector module in that they extend the business object handler functionality from the Java component of the connector module. ABAP handlers reside in the SAP application as ABAP function modules and communicate directly with Y_XR_RFC_DO_VERB_NEXTGEN. ABAP handlers are needed to get business object data into or out of the SAP application database.
Figure 6 illustrates the business object processing components of the ABAP Extension Module and their relationship to one another. Notice that for a single business object handler (doVerbFor()) and business object router (Y_XR_DO_VERB_NEXTGEN) there are multiple ABAP handlers.
Figure 6. Adapter-provided business object processing components
ABAP handlers are responsible for adding business object data into the SAP application database (Create, Update, Delete) or for using the business object data as the keys to retrieving data from the SAP application database (Retrieve).
The adapter provides generic ABAP handlers. For example, function module Y_XR_RFC_DYNAMIC_TRANSACTION supports flat business objects for Create, Update, Delete, and Retrieve operations.
The WebSphere business integration system provides a meta-data repository and a generic ABAP handler to support flat business objects. The adapter also provides an ABAP handler (Y_XR_IDOC_HANDLER) to support hierarchical business objects; however, you must develop an additional business-object-specific ABAP handler for each hierarchical business object that you need to support.
The WebSphere business integration system provides tools that facilitate the development process. For more information on developing business objects and ABAP handlers, see Developing business objects for the ABAP Extension module and Appendix C, Generating business object definitions using SAPODA.
Event notification refers to the collection of processes that notify the connector of SAP application object events. Notification includes, but is not limited to the type of the event (object and verb) and the data key required for the external system to retrieve the associated data.
Figure 7 illustrates the event notification process, which uses the pollForEvents() method.
Figure 7. Event notification process
Event notification for the connector consists of two functions:
Event polling consists of three functions that are carried out by the pollForEvents() method:
Event request is the process of polling and retrieving events from the event table in the SAP application. The event request mechanism of the Java component has a counterpart function module in the SAP application, Y_XR_RFC_EVENT_REQUEST. This function retrieves events from the connector's ABAP event table, YXR_EVENTS.
Every triggered event enters the event table with an initial status of prequeued (status marked as P in the event table) and a default event priority of zero. Before an event can be processed, its status must be changed to queued (Q in the event table). The priority of an event must be zero before the connector retrieves the full object that it represents. For more information on event priority, see Event Priority.
The status of an event changes from prequeued to queued if there are no database locks for the combination of the user who created the event and the event's key. If locks exist, the status of the event is set to locked (L in the event table) and the event is requeued. An ABAP constant, C_MAXIMUM_REQUEUE, defines of the number of times that an event can be requeued. If the maximum number (defaulted to 100) is attained, then the event is archived to the event archive table.
After preprocessing all prequeued events, the ABAP function module Y_XR_RFC_EVENT_REQUEST selects the events to return to the event request method in the Java component of the connector module (only events with a status of queued can be selected). The connector-specific configuration property PollQuantity (defaulted to 20) determines the maximum number of events returned for a single poll. For more information, see Installing and configuring the connector.
The event request mechanism performs the event selection process in two steps:
Events are dedicated to a specific integration broker in the event distribution table (/CWLD/EVT_DIS). The name of the integration broker specified in this table must match the name specified in the shortcut that starts the connector. For example, the standard shortcut for an SAP connector running on Windows has the format:
...\start_SAP.bat SAPconnectorName integrationBrokerName -cConfigFileName
When WMQI is the integration broker, the WebSphere business integration system identifies the integration broker specified in the event distribution table by getting values from the connector's startup command:
For example, if the connector-specific configuration property PollQuantity is kept at 20 and there are 8 events dedicated to the specific connector and the integration broker, the mechanism selects 12 additional events that are not configured for event distribution.
When WMQI is the integration broker and only one Queue Manager has been configured, the names of the queues must be unique for each instance of the integration broker. When WMQI is the integration broker and a cluster has been configured, the names of the queues must be unique for each integration broker within the cluster.
If desired, you can incorporate the name of the broker (as specified in the integrationBrokerName parameter of the startup command) or the name of the connector into the names of the queues. For example, if two brokers are named WMQI1 and WMQI2, their respective ADMINOUTQUEUEs might be named ADMINOUTQUEUE_MQI1 and ADMINOUTQUEUE_MQI2, respectively.
The event request function produces an array of events to be processed from the YXR_EVENTS event table. It passes these events to the event processing function, which handles them one at a time in the following manner:
After each event is processed by event request, it is returned to the SAP application using function module Y_XR_RFC_EVENT_RETURN. This function module makes a copy of the processed event, adds it to the event archive table (YXR_ARCHIV), and then deletes the original entry from the event table.
Archived events include successfully processed events, events that were processed but terminated in an error, and unsubscribed events. Each event has a status that can indicate one of the following conditions:
Use the IBM (CROSSWORLDS Connector Tool in the SAP application to administer the event archive table. Connector Tool enables an administrator to display and truncate the archive table and to resubmit events for processing. For more information about maintaining the archive table and setting up log truncation, see Managing the ABAP Extension module.
The connector is event-driven. In order to get events out of the SAP application, you need to implement an event triggering mechanism for each IBM WebSphere-supported business object. Event triggering for the connector comprises three functions:
Event detection is the process of identifying that an event was generated in the SAP application. Typically, connectors use database triggers to detect an event. However, because the SAP application is tightly integrated with the SAP database, SAP allows very limited access for direct modifications to its database. Therefore, the event detection mechanisms are implemented in the application transaction layer above the database.
The IBM WebSphere Business Integration Adapter for mySAP.com commonly uses three mechanisms to detect an event in the SAP application:
Regardless of the detection mechanism used, all events are triggered using the event trigger Y_XR_ADD_TO_QUEUE. Once an event is identified by one of the event detection mechanisms, it is passed to the event trigger. The IBM WebSphere Business Integration Adapter for mySAP.com includes an event trigger (Y_XR_ADD_TO_QUEUE) that commits events to the event table (YXR_EVENTS). Specifically, it adds a row of data for the object name, verb, and key that represents the event.
All events are added to the current events table using Y_XR_ADD_TO_QUEUE. In addition to adding a row of data to YXR_EVENTS, Y_XR_ADD_TO_QUEUE can be set up for:
Event filtering, event distribution, and event priority are executed as part of the event trigger and by no other program. They result in either the event's restriction (filtering), or modification (event distribution and event prioritization).
Figure 8 illustrates the event triggering functionality inside the SAP application. The events E1, E2, and E3 are received by the event trigger Y_XR_ADD_TO_QUEUE. E1 represents a Customer event and E3 represents an Order event. Event distribution is set up so that all Customer objects are handled by SAPconnector1 and all Order objects are handled by SAPconnector2. In this environment, both connectors use the same integration broker. Because E1 is a Customer object, it is polled by SAPconnector1 and because E3 is an Order object, it is polled by SAPconnector2. E2 is an Inventory object that is filtered out by code in the restriction program YXRRESTR that restricts inventory objects from Plant 100.
Figure 8. Event triggering with function module Y_XR_ADD_TO_QUEUE
Attention: If you are using multiple connectors to poll, you must dedicate every subscribed event to a specific connector. Failure to do so may result in duplicate events delivered. You must guarantee that there is no dependency between objects dedicated to different connectors, because this may result in events being delivered out of sequence.
For example, assume you have a single integration broker named CROSSWORLDS1 that subscribes to two different business objects, BO_A and BO_B. The BO_A business object is small and can be retrieved quickly whereas BO_B is large and takes much longer to retrieve. With two connectors polling, SAPconnector1 and SAPconnector2, you can set up the event distribution table so that SAPconnector1 retrieves BO_A and SAPconnector2 retrieves BO_B. SAPconnector1 can continuously poll small objects of type A, while SAPconnector2 focuses on the larger type B objects.
By default, all events are given a priority of zero. An object's priority is configured in the same ABAP table as event distribution.
Once the event trigger inserts an event into the event table, the event is committed to the database with its event distribution and event priority values set. At this time, only polling can modify the event. When the event polling processes is completed, meaning the event was retrieved from the SAP application and processed by the Java component of the connector, a copy o f the processed event is added to the event archive table (YXR_ARCHIV). The original event is then deleted from the event table.