Integration

SAP J2EE Engine 6.20

Integration

SAP J2EE Engine 6.20

Contents
Introduction ...................................................................................................3 SAP Web Application Server Architecture ......................................................4 Internet Communication Manager (ICM) ......................................................... 5 Clustering..................................................................................................... 6 Request Handling and Dispatching ................................................................. 7 ABAP <-> Java Communication .....................................................................8 SAP Java Connector (JCo).............................................................................. 8 Remote Function Call (RFC) ........................................................................... 8 Scenario....................................................................................................... 9 RFC Library ................................................................................................ 10 Call Java Functions from SAP R/3 ................................................................. 11 Why a Repository? ...................................................................................... 11 Configuration and Testing............................................................................ 11 Architecture................................................................................................ 13 R3Startup Manager ..................................................................................... 14 Usage of Native Libraries for SAP Web AS SAP J2EE Engine Integration ........ 15 R3Startup Service........................................................................................ 16 SAP Web AS - SAP J2EE Engine Communication ............................................ 16 Command Interface .................................................................................... 17 Logging and Monitoring .............................................................................. 18 Logging ..................................................................................................... 18 Monitoring System ...................................................................................... 18 Application Tracing ..................................................................................... 18

2/19

Integration

SAP J2EE Engine 6.20

Introduction
This document aims to describe how the integration between SAP J2EE Engine and SAP Web Application Server (SAP Web AS) is designed. There are several areas that take part in this integration. Some of the most important are: ABAP <-> Java communication R3Startup Manager R3Startup Service Logging, monitoring, and application tracing.

Note: For information on logging in SAP R/3 system, see http://help.sap.com -> SAP

Library -> mySAP Technology Components -> SAP Web Application Server -> SAP J2EE Engine -> Integration of the Security Functions of SAP Web Application Server and SAP J2EE Engine.
For reasons of consistency the document covers at first the aspects connected with the architecture, as well as with the position that SAP J2EE Engine has inside SAP Web AS.

3/19

Integration

SAP J2EE Engine 6.20

SAP Web Application Server Architecture

SAP Web Application Server Architecture

In this collaborative architecture the user benefits from several aspects: One central access point for HTTP(S) requests; The Server Cache in Internet Communication Manager (ICM) can be used by both engines; Common Java and ABAP administration and monitoring; Common installation; Common certificate administration (the HTTPS connection is terminated in the ICM); Central HTTP logfile or capture log of all requests/responses; Coexistance of ABAP and Java engine.

Note: For more information about the SAP Web Application Server Architecture, see SAP Web AS documentation.

4/19

Integration

SAP J2EE Engine 6.20

Internet Communication Manager (ICM)

The ICM ensures the communication between the SAP Web Application Server and the SAP J2EE Engine using the HTTP and HTTPS protocols. It processes requests from the Internet that have URLs with the server/port combination, which the ICM responds to. ICM ensures the client connection with SAP Web servers (ABAP and JAVA). The client cannot access directly the Web Servers. It has only access to the HTTP socket opened by the ICM. ICM opens clients sockets directly to the Web Server and redirects to it the client request. It also sends the server response back to the client. ICM redirects the HTTP request from the client to the server unchanged. It only adds few "trailer" bytes before each piece to obtain correct manipulation of the connections, because lots of client requests pass through one socket. This "trailer" is used also to send information to the Web Server about the socket, which the Web Server cannot access. For example: the IP address of the client, the protocol type (i.e. HTTP or HTTPS), the required certificate if the socket client ICM is SSL. The HTTP Dispatcher takes care that these values are sent to the application, not the ones taken from the socket. One socket is used from lots of clients, i.e. there is not a new client socket for each server client. The socket ICM J2EE can be closed only by the ICM, i.e. it is not influenced by the KeepAliveTimeout property of the Dispatcher and so on. ICM takes care for the manipulation of the persistent and non-persistent connection to the client. The IP taken from the clients socket of the server (in this case of the ICM) is not used. Instead the IP taken from the protocol is used. The Web Server uses it to forward the response. Also the methods of the Servlet API for getting the client IP use it. If the connection Client ICM is through SSL, the ICM verifies the socket on SSL level and opens new clean HTTP socket to the Web Server. This socket is used to send HTTP request without using SSL. It also sends the certificate that has been read from the socket as a byte array. The Web Server can use the certificate for login or to grant it to the application through the Servlet API. In the ICM J2EE protocol the trace level is shown. The ICM sets the trace level of the HTTP Server. The trace level shows how to log the information during parsing the ICM protocol of the dispatcher (logging errors and debugging depends on the level). If the trace level is set, additional information from the HTTP request parsing is logged. The information can be viewed in the files of the Log service.

5/19

Integration

SAP J2EE Engine 6.20

The static HTTP requests are cached in two levels J2EE cache and ICM cache. By default the files cached in both places coincide, but this still depends on the settings of the J2EE Engine and ICM. By default the ICM cache keeps the files of J2EE for 24 hours. The J2EE Engine decides how much time (if any at all) the files will be stored using the HTTP header "sap-cache-control", whose value sets the time (in seconds) for which the files will be cached in the ICM. To set this value, use the HTTP Server property SapCacheControl. The default value of this property is 86400. When the J2EE Engine cache is cleared, this also triggers the clearing of the ICM cache. This mechanism is done by using the Web AS J2EE communication. The J2EE Engine cache can be cleared at deploy, redeploy, update, or remove phases of an application, by using the clearhttpcache command of the HTTP Server or by using the ICM administration tools. All the files cached in the ICM, which are from the J2EE Engine has alias "J2EE/" + <web_application_name>. This alias is used for listing or deleting of cached files from the ICM administration tools. Note: For more information about ICM, HTTP Cache, and how to enable redirect from ICM to SAP J2EE Engine, see the SAP Web Application Server documentation:

SAP Library->mySAP Technogy Components->SAP Web Application Server>SAP J2EE Engine->Integrating the SAP J2EE Application Server>Administration of the SAP Web Application Server SAP Library->mySAP Technogy Components->SAP Web Application Server>Client/Server Technology->Architecture of the SAP Web Application Server SAP Library->mySAP Technogy Components->SAP Web Application Server>Client/Server Technology->Architecture of the SAP Web Application Server>Parameterizing the ICM and the ICM Server Cache->Sample Profile for the ICM

Clustering
The SAP J2EE Engines state controller, backup state controller, dispatcher, and application nodes belonging to one SAP system form a cluster. The host, on which the Central Instance (CI) is running, serves as cluster host. Note: The SAP J2EE Engine can only be started by starting the Web Application Server. The SAP J2EE Engine on a Dialog Instance (DI) only starts, if the CI and the SAP J2EE Engine on the CI is running.

6/19

Integration

SAP J2EE Engine 6.20

Request Handling and Dispatching

You can configure the SAP Web AS so that it: can only process ABAP requests, for example HTTP(S) requests that must be processed by the Internet Communication Framework (ICF). The ICF provides the environment for handling HTTP requests in work processes on an SAP System (server and client). If you are using the system as a server, you need a HTTP Request Handler, which you can create yourself. Defining the HTTP request handler yourself allows you to use the ICF flexibly in your application. However, HTTP request handlers are also shipped with the SAP System. The Internet Communication Framework (ICF) serves as the bridge between the C kernel in the SAP System and the application program (in ABAP). can process both ABAP and J2EE requests (that is, HTTP(S) requests that must be processed by the SAP J2EE Engine). can only process J2EE requests.

>mySAP Technogy Components->SAP Web Application Server->SAP J2EE Engine>Integrating the SAP J2EE Application Server

Note: For more information about request handling and dispatching, see SAP Library-

7/19

Integration

SAP J2EE Engine 6.20

ABAP <-> Java Communication

SAP Java Connector (JCo)
The SAP Java Connector is a toolkit that allows a Java application to communicate with any SAP system. It combines an easy to use API with unprecedented flexibility and performance. The package supports both Java to ABAP System as well as SAP System to Java calls. The SAP Java Connector is the best choice for building SAP-enabled Java applications because of the following features: High-performance JNI-based Remote Function Call (RFC) middleware Supports SAP R/3 system 3.1H and higher (and other mySAP components that have Business Application Provider Interfaces (BAPIs) or RFMs). Supports inbound (Java client calls BAPI or RFM) and outbound (ABAP calls Java server) calls. Supports synchronous, transactional and queued RFC. Supports client pooling (good for web servers). Multi-platform Complete and correct code-page handling (incl. multi-byte languages) Easy to install and deploy.

JCo is essential for the communication between SAP J2EE Engine and SAP Web Application Server. It is acting as Java-Wrapper for the RFC-Library. Note: You can download JCo at http://service.sap.com/connectors. For SAP J2EE Engine 6.20 you need the 2.0 version. Follow the installation instructions to enable the SAP J2EE Engine to connect to SAP systems.

Remote Function Call (RFC)

RFC is an SAP interface protocol, which simplifies the programming of communication processes between systems. RFCs enable you to call and execute predefined functions in a remote system or in the same system. RFCs manage the communication process, parameter transfer and error handling. In SAP J2EE Engine 6.20 RFC is used for processing ABAP to Java requests. A function is provided for receiving calls from the SAP systems. This is done by registering SAP J2EE Engine as an RFC destination.

8/19

Integration

SAP J2EE Engine 6.20

The J2EE Engine RFC Engine Service processes calls from the SAP systems. It dispatches the calls to a stateless session bean, which is registered in the JNDI. By the naming convention the JNDI name used is identical to the name of the SAP function module. Technically, the service is based on the JCO (SAP Java Connector). The bean must implement the public void processFunction(JCO.Function function) method. The JCO.Function contains both the input and output parameters. To parse correctly the function calls from the SAP system, the JCO needs a repository. This is a remote connection to a repository of an SAP system.

Scenario

1. 2. 3. 4.

On startup the RFC Engine service connects to the repository of an SAP system. The RFC Engine service registers itself at the Gateway with a defined name. It is possible to register it under different names and at different Gateways. An SAP system calls a function for the registered RFC destination. Note: Make sure that the function is defined in the repository. The Gateway forwards the call to the RFC Engine.

9/19

Integration

SAP J2EE Engine 6.20

5. 6. 7. 8.

The RFC Engine looks in the JNDI for the EJB, which is registered under the function name. The RFC Engine calls the processFunction(JCO.Function) method of the EJB found. The results of that call (the modified JCO.Function) are passed to the Gateway. The Gateway passes the results back to the SAP system.

RFC Library
The RFC Library offers an interface to an SAP system. The RFC library is the most commonly used and installed component of existing SAP software. This interface provides the opportunity to call any RFC function in an SAP system from an external application. Moreover, the RFC Library offers the possibility to write an RFC server program, which is accessible from any SAP R/3 system or an external application. Most SAP R/3 connectors use the RFC library as communication platform to SAP systems. The most important design features of the RFC Library are: Working with the native RFC protocol. Maximum functionality, that is almost all features of RFC in SAP R/3 systems have to be supported by the RFC Library, too. Maximum performance. Maximum flexibility. Full compatibility to other RFC releases.

The RFC library is available for all OS platforms: Windows librfc32.dll Unix/Linux librfccm.so, librfccm.sl, and so on.

On errors it writes trace-files into the current working-directory:

rfc<GUID>.trc: One file per call with detailed trace-info. dev_rfc.trc: Combined file for all errors.

10/19

Integration

SAP J2EE Engine 6.20

Call Java Functions from SAP R/3

The Java class JCO.Server can be used to create an RFC server. It registers under a program ID at an SAP Gateway. In the SAP System (Transaction SM59) the same information (program ID and SAP Gateway) will be maintained to define a TCP/IP-destination. ABAP programs can now call functions on this external destination On the Java side those function calls will be received in a callback method:
handleRequest(JCO.Function function)

The function contains both the input and output-parameters

Why a Repository?
The RFC-protocol sends only the values of the function call as a byte array, but does not send the function definition. Therefore the receiver needs a Repository to parse those values. Example: Receive byte-array: Hello199 Parse into 3 parameters: Hello, 1, 99 Although this Repository and the function-definitions could be created manually, typically an existing SAP Repository is used. The advantage is, that then the Repositories on both sides (Java and ABAP) are always the same. Note: When using an SAP Repository, the RFC Server is at the same time an RFC Client! This is important for understanding how the RFC Server must be configured.

Configuration and Testing

1. Install the SAP J2EE Engine 6.20. 2. Run SAP J2EE Engine and start the Visual Administration Tool. Configure the RFC Engine Service in a way described below:

11/19

Integration

SAP J2EE Engine 6.20

a. Define the RFC destination: i. Program ID the name of this RFC-destination; ii. Gateway host and Gateway service Gateway, where to register; iii. Number of processes maximum number of parallel threads; b. Define the repository all other parameters (User, Password, Host, Client, System number, and so on) are used to connect to the repository of an SAP System. Note: For more information about the RFC Engine and its properties, see Administration Manual->Services Administration Reference->RFC

Engine Service

3. Deploy an EJB for testing. The EJB must support the processFunction(JCO.Function) method and must be bound in the JNDI with the name of the SAP function. Before deploying you have to specify the reference from the application to the JCO library. You can do this from SAP J2EE Engine Deploy Tool. Choose the Deployer Tab, then choose Deploy>Libraries from the toolbar menus. In the Libraries section choose the References Tab and add the jco library. The above procedure is valid if you deploy the application from the SAP J2EE Engine Deploy Tool. In case you deploy it from the shell console, you can use the changeref shell command. Example: application which you are deploying.
changeref m <application_name> jco where <application_name> must be replaced with the name of the

4. Configure the RFC-destination in the SAP System: a. Transaction SM59 use this transaction to create a new TCP/IP connection. Enter the Program ID and the Gateway, which you specified in step 2.a. b. Save and press the Test Connection button to check the connection. 5. Call a Function in SAP J2EE Engine from the SAP System: a. Transaction SE37 use this transaction to enter the name of the function and press Single Test.

12/19

Integration

SAP J2EE Engine 6.20

b. Enter the RFC target system (which you configured in 4.a.) and all necessary values for the function. c. Press the execute-button to call the EJB in SAP J2EE Engine.

Architecture
Connectivity between SAP J2EE Engine and SAP Web AS is available via several networking mechanisms (JCo via RFC, SOAP, ), which is applicable for loosely coupled applications following the currently popular web service approach. For tightly coupled applications, this is a less favourable solution. A tighter integration approach is required for the applications that are Java-ABAP mixtures. Fast RFC provides an additional fast local communication channel for JAVA-ABAP components via shared memory and an efficient representation response mapping of the data types of both systems. This gives the opportunity to use the other communication model (RFC/JCo) for gross granularity communication and to switch to fine granularity communication for tighter coupled applications.

13/19

Integration

SAP J2EE Engine 6.20

R3Startup Manager
This manager starts the state controller, the backup state controller, and the application nodes, controls the processes of the application nodes, and connects and communicates with the SAP Web Application Server. It runs on all cluster nodes. The manager that runs on the dispatcher node takes the dispatchers process ID and sets it to be system property. It also opens a socket for communication on a port specified in the property files. The R3Startup Manager that runs on application nodes and the state controllers writes in a log file the process identifications of a corresponding cluster element. By default, the log file location is <SAPj2eeEngine_install_dir>/tools/r3startup/clusterpids. To accomplish this function the R3Startup Manager uses a native method from a library located in <SAPj2eeEngine_install_dir>/tools/r3startup/logpid.dll. This function gives to the Web Application Server dispatcher the opportunity to stop the SAP J2EE Engine cluster, killing the processes of the started elements even in situations when the dispatcher is not properly shutdown (its process has been killed without giving it the chance to stop the application nodes and state controllers it has started) and than has been started again. The following properties concern the integration:
r3environment - shows whether the cluster element is started in SAP Web Application Server environment. PIDsLogFileName specifies the filename where the process IDs are logged. InfoLogFileName, NoticeLogFilename, WarningLogFileName, and DebugLogFileName specify the filenames to which the different types of log messages for R3Startup Manager are written. CONNECT_PORT a server socket port to which the SAP Web Application Server connects. This port establishes a connection between the SAP Web Application Server and the SAP J2EE Engine cluster. KILL_OLD_SERVER_PIDS

For more information on R3Startup Manager, see the Managers Administration Reference section in the Administration Manual.

14/19

Integration

SAP J2EE Engine 6.20

Usage of Native Libraries for SAP Web AS SAP J2EE Engine Integration
Native libraries are used to retrieve process IDs. This cannot be done with pure Java, because no means for dealing with process IDs are provided in the Java programming language. R3StartupManager performs loading of native libraries only if its property r3environment is set to Yes (the default value of the property is No). It searches for a native library named pidmanager (respectively pidmanager.dll, libpidmanager.so), which is situated in the SAP Web Application Server kernel. When SAP J2EE Engine dispatcher node starts, the ID of its process is read and sent to the SAP Web AS dispatcher. This is done so that the SAP Web AS dispatcher can kill the process of SAP J2EE Engine dispatcher in the cases when the latter has not shut down after receiving a shutdown command and after a certain period of time (this timeout is a property of SAP Web AS dispatcher). The SAP Web AS dispatcher can also perform some life checks using the process ID. Native libraries are also used in application nodes for logging application node process IDs (default log file is <SAPj2eeEngine_install_dir>/tools/r3startup/clusterpids). After that in cases when SAP J2EE Engine dispatcher node crashes without being able to stop the application nodes, the next time it starts it kills the logged process IDs if and only if the KILL_OLD_SERVER_PIDS property of R3StartupManager is set to Yes.

15/19

Integration

SAP J2EE Engine 6.20

R3Startup Service
The R3Startup Service can be started only on SAP J2EE Engine dispatcher. This service establishes the connection with the SAP Web AS dispatcher through the socket created by the R3Startup Manager and holds up permanently running the cluster elements (when one of the elements crashes, the service notifies the R3Startup Manager, and the manager restarts the corresponding cluster node), specified in the <SAPj2eeEngine_install_dir>/cluster/dispatcher/services/r3startup/properties file. The file format is:
elements the number of elements that the service must run and support.

The elements are of the following format: o element_X_id cluster ID of the element; o element_X_dir a path to the element, where X is number of the subsequent cluster element. The first element number is 0, which means that the names of its properties will be element0name and element0dir. Other properties log files and timeout for soft shutdown.

SAP Web AS - SAP J2EE Engine Communication

For internal communications between SAP Web AS and SAP J2EE Engine dispatcher, a simple, extensible interface is used: SAP Web AS binds a local TCP/IP socket; SAP Web AS starts SAP J2EE Engine dispatcher and informs it about the communication port. The following parameters are passed to the SAP J2EE Engine dispatcher via system properties. These additional parameters are appended to the value of the profile parameter rdisp/j2ee_server: o -DCONNECT_PORT=<port> the communication port between SAP Web AS and SAP J2EE Engine. o -DLISTEN_PORT=<port> the LCOM-communication port. o -DSAPSYSTEM=nn a 2-digit system number, used for identification of the system resources needed by SAP Web AS. o -DSAPSYSTEMNAME=<sid> a 3-digit system id used by SAP Web AS. o -DSAPMYNAME=<name> the application server name o -DSAPPROFILE=<name> the profile filename. If the connection to SAP J2EE Engine is lost, the application node will be restarted.

16/19

Integration

SAP J2EE Engine 6.20

As soon as the J2EE Engine connects to the SAP Web AS dispatcher, the local socket will be closed for security reasons. Data is exchanged in UTF8 format. Only character strings can be used, avoiding converting problems. The first four characters determine the message length, without counting these four characters. The first byte is the highest order byte, and the last one is the lowest order byte. This encoding gives an integer representation, regardless of the internal representation.

For communication between the SAP Web AS dispatcher and the SAP J2EE Engine dispatcher a local TCP/IP network connection is established. The SAP Web AS dispatcher binds a local port and passes the port number to the SAP J2EE Engine dispatcher via Java System Property. After the initialization the SAP J2EE Engine dispatcher connects to this local port and the communication channel is established. If the network connection is closed for any reasons, it is assumed that the SAP J2EE Engine dispatcher failed and the SAP Web AS dispatcher tries to restart it.

Command Interface
Commands: SAP J2EE Engine -> SAP Web AS

PID=<pid> the java VM process ID. Checks the SAP J2EE Engine processes. HTTP_PORT=8088 SAP J2EE Engine HTTP listen port; HTTPS_PORT=1433 SAP J2EE Engine HTTPS listen port (SSL); ACTIVE SAP J2EE Engine is started and operational; INACTIVE SAP J2EE Engine is not operational; LB=10 the weighting factor for load balance. 10 is a relative strength of the

J2EE application node (maximum 1000), i.e. an application node with weighting factor 20 will get twice of requests as an application node with 10. INVALIDATE_ETAG=<etag> the message is forwarded to ICMan to invalidate the specified <etag>. INVALIDATE_URL=<url> the message is forwarded to ICMan to invalidate the specified <url>.

All other messages are ignored

Commands: SAP Web AS -> SAP J2EE Engine

HARDSHUTDOWN immediately stops SAP J2EE Engine; SOFTSHUTDOWN stops SAP J2EE Engine after finishing all started requests.

All other messages are ignored.

17/19

Integration

SAP J2EE Engine 6.20

Logging and Monitoring

Logging
A record of normal or exceptional events; Switched on during normal operation; Log messages are emitted to categories, which describe distinguished problem areas, such as database problems or security auditing; Log messages are also visible in the trace.

For more information about SAP J2EE Engine logging system, see the Administration Manual->Configuration Tasks->Using the Log System and Monitoring section.

Monitoring System
SAP J2EE Engine monitoring system provides options for monitoring the SAP J2EE Engine both by SAP J2EE Engine-specific tools (such as, Visual Administrator, and Browser-Based monitoring), and by exporting monitor data to external systems (such as, SAPs CCMS). The monitor data is stored and analysed, and is an essential part of the SAP J2EE Engine work process. For more information about SAP J2EE Engine monitoring system, see the

Administration Manual->Configuration Tasks->Using the Log System and Monitoring

section.

For more information about SAPs CCMS, see SAP Library and the SAPs CCMS documentation.

Application Tracing
Reconstruction of the control flow of a running application; Used during development or problem detection in productive systems (alternative to debugging); Application tracing is switched off during a normal operation; Trace messages are emitted to locations, which describe delimited code areas, such as packages or classes.

18/19

Integration

SAP J2EE Engine 6.20

For more information about SAP J2EE Engine application tracing system, see

Administration Manual->Configuration Tasks->Setting up SAP J2EE Engine 6.20 for Application Tracing section.

19/19