How the vision connector framework works

The connector interacts with an SAP application using connector modules. The connector modules make calls to SAP's Native Interfaces and pass data (business object or event data) to and from an SAP application. The connector's flexible design enables different modules to be used for different tasks such as initializing the connector with the SAP application or passing business object data.

Communication between the connector and an SAP application

The connector uses SAP's Remote Function Call (RFC) library to communicate with an SAP application. SAP's RFC API allows external programs to call ABAP function modules within an SAP application.

Processing business objects

The connector is metadata driven. Metadata, in the WebSphere business integration system, is application-specific data that is stored in business objects and that assists a connector module in its interaction with the application. A metadata-driven connector module handles each business object that it supports based on metadata encoded in the business object definition rather than on instructions hard-coded in the connector module.

Business object metadata includes the structure of a business object, the settings of its attribute properties, and the content of its application-specific information. Because connector modules are metadata driven, they can handle new or modified business objects without requiring modifications to the connector-module code.

The vision connector framework uses the value of the verb application-specific information in the top-level business object to call the appropriate connector module to process the business object. The verb application-specific information provides the classname of the connector module.

The verb application-specific information of most top-level business objects must identify the classname of the connector module. The syntax of this verb application-specific information is:

AppSpecificInfo = PartialPackageName.ClassName,
 

For example:

AppSpecificInfo = sap.sapextensionmodule.VSapBOHandler,
 

In this example, sap.sapextensionmodule is the partial package name, and VSapBOHandler is the classname. The full package name includes the com.crossworlds.connectors prefix, which the WebSphere business integration system adds to the name automatically. In other words, the full text of the example is:

com.crossworlds.connectors.sap.sapextensionmodule.VSapBOHandler
 
Note:
The verb application-specific information of most top-level business objects must use a comma (,) delimiter after the connector classname. However, the Server verb, which is used by the RFC Server Module, is delimited instead by a semi-colon (;). For information about the Server verb, see "How the RFC Server Module works" and "Supported verbs".

You need not specify the package name and classname for the verb application-specific information if the business object is used:

Important:
Customer-generated connector modules that process business objects for the BAPI and RFC Server Modules must specify a full package name, which must begin with bapi. For example, bapi.client.Bapi_customer_getdetail2. The full package name in this example is bapi.client, and the classname is Bapi_customer_getdetail2.

Most business object processing is specific to each connector module. By default the connector uses the ABAP Extension module. For more information on business object processing for the ABAP Extension module, see "Business object processing", Business object data and ABAP handlers, and Configuring an object to be archived.

For more information on specifying verb application-specific information for the ALE module, see "Event processing" and Processing multiple IDocs with a wrapper business object.

Processing multiple concurrent interactions

The system-wide Connector Framework can create separate threads for processing an application event and a business object request. When processing multiple requests from the integration broker, it can create multiple threads to handle multiple business object requests. For example, when InterChange System is the integration broker, the connector can receive multiple business object requests from multiple collaborations or from a multi-threaded collaboration.

Important:
BAPI business object handlers generated before the connector for SAP version 4.3.0 are not thread-safe. To guarantee data consistency and integrity when using multi-threading, you must regenerate these business object handlers. The business objects do no require any change.

Figure 3 illustrates the multi-threading architecture.

Figure 3. Multi-Threading architecture of the connector for SAP

Event processing

The connector performs the following steps when handling a poll call:

  1. The system-wide Connector Framework creates a single dedicated thread to handle poll calls. This thread calls the pollForEvents() method of the vision connector framework at the frequency specified in the PollFrequency configuration property.
  2. The thread polls SAP, which uses a dialog process to locate and return the event.
    Note:
    If the connector's MaxNumberOfConnections configuration property evaluates to a number greater than 1, the vision connector framework dedicates a connection to SAP for polling. If MaxNumberOfConnections evaluates to 1, event and service-call request processing share a single connection to SAP.

The polling thread dies only when the connector shuts down.

Note:
Because the RFC Server connector agent pushes events out of SAP instead of polling for events, it spawns its own threads instead of using threads created by the connector framework. Because the ALE connector agent uses the RFC Server connector agent to access events, it also it spawns its own threads instead of using threads created by the connector framework when it processes events.

Request processing

Independently of polling, the system-wide Connector Framework can create multiple request-processing threads, one for each request business object. Each request thread instantiates the appropriate business object handler.

For example, when processing business object requests from InterChange Server, the number and type of business object handlers depends on the number and type of the collaborations sending the requests:

If the connector's MaxNumberOfConnectionsconfiguration property evaluates to a number greater than 1, the vision connector framework dedicates one connection to SAP for polling and allocates the remaining connections to a pool used only for request processing.

As illustrated in Figure 3, the connector performs the following steps when handling a business object request:

  1. The system-wide Connector Framework creates a separate thread for each business object request. Each thread calls the doVerbFor() method of the Vision business object handler.
  2. If the connector's MaxNumberOfConnections configuration property evaluates to a number greater than 1, the Vision business object handler checks the vision connector framework's connection pool to determine if a connection handle is available.

    If the connector's MaxNumberOfConnections configuration property evaluates to 1, the Vision business object handler shares a connection with event processing.

  3. SAP releases the dialog process after it completes processing and sends a return code.
  4. The connector releases the connection handle after it receives the return code from SAP.

Setting the number of available connections

Use the MaxNumberOfConnections configuration property to specify the maximum number of connection handles available. The number of connections cannot exceed the number of dialog processes.

SAP locks the dialog process while processing an interaction, releasing it only when the interaction completes. Therefore, multiple concurrent requests lock an equal number of dialog processes until processing finishes.

Important:
Before setting a value for MaxNumberOfConnections, contact your SAP BASIS administrator to determine an appropriate value to maximize throughput without negatively affecting performance on the application server.

Setting multiple connections

By default the connector supports only single-threading. To cause the connector to support multiple threads, remove the following flag from your connector startup script:

UNIX

-tMAIN_SINGLE_THREADED

Windows

-tSINGLE_THREADED

For more information, see in the Connector Development Guide for Java.

Processing locale-dependent data

The connector has been internationalized so that it can support multi-byte character sets. When the connector transfers data from a location that uses one character code set to a location that uses a different code set, it performs character conversion to preserve the meaning of the data.

Note:
The CrossWorlds Station log is available only in English.

The Java runtime environment within the Java Virtual Machine (JVM) represents data in the Unicode character code set. Unicode contains encodings for characters in most known character code sets (both single-byte and multibyte). Most components in the IBM WebSphere business integration system are written in Java. Therefore, when data is transferred between most IBM WebSphere business integration components, there is no need for character conversion.

Because this connector is written in Java, it does not need to convert application data (including data in an IDoc file) written in native encoding. The SAPJCo library converts such application data to Unicode before the connector processes it. Figure 4 illustrates the components involved in data conversion.

Figure 4. Configuring agent properties

To log error and informational messages in the appropriate language and for the appropriate country or territory, configure the Locale standard configuration property for your environment. For more information on these properties, see Appendix A, "Standard Configuration Properties for Connectors".

Important:
The character code set that SAP applications use for Japanese is SAP-8000. This code set does not support MS932 characters. Also, SJIS maps some characters to non-standard Unicode characters. Therefore, the SAPJCo library cannot handle some characters. If these characters are included in the SAP application or the IBM WebSphere business object, the connector replaces them with the # or ? character. When data contains these characters, it is not processed correctly, and the connector does not report errors.

Copyright IBM Corp. 1997, 2003