Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

Contents SAP J2EE Engine Distributions....................................................................3 SAP Unattended Installation ................................................................3 SAP J2EE Engine Standalone Installation ..............................................4 Comparison Table...............................................................................4 R3Startup Manager. R3Startup Service .......................................................9 Overview ...........................................................................................9 Running SAP J2EE Engine in an R/3 Environment. Communication........ 11 Usage of Native Libraries for R/3 – SAP J2EE Engine Integration .......... 13 R3Startup Service Errors ................................................................... 14 Logging in SAP R/3 System using R3AccountLoginModule........................... 15 Using SAP R/3 LoginModule............................................................... 15 ICMan – SAP J2EE Engine Communication ................................................ 21

2/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

SAP J2EE Engine Distributions SAP J2EE Engine is a J2EE-compliant Application Server. Its installation package is distributed depending on the role and the purpose of the server. There are two basic installation types: · ·

SAP Unattended distribution – this type installs SAP J2EE Engine as a part of SAP R/3 System, within the SAP Installer pack Standalone distribution – SAP J2EE Engine as a separate installation. It can provide connection with an R/3 System (when available), if the properties of SAP J2EE Engine are specified as in the SAP Unattended distribution

Both installation types are oriented to work in a particular environment. The user chooses the type at installation time in order to retrieve the appropriate server configuration. It concerns specific settings of the server. For information on the properties meaning, please refer to Services Administration Reference and Managers Administration Reference chapters in Administration Manual.

SAP Unattended Installation SAP J2EE Engine 6.20 is installed along with a SAP R/3 System and cooperates with Web Application Server 6.20. This means that SAP J2EE Engine is the J2EE platform of the R/3 System and will receive requests from Web Application Server 6.20. A specially designed Java class (TFReplace.class) configures all properties at installation time. Please check the specific properties default values in the Comparison Table. They are calculated as described.

3/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

SAP J2EE Engine Standalone Installation This type of installation provides SAP J2EE Engine 6.20 as a separately running J2EE Application Server.

Comparison Table Dispatcher The following properties’ values differ, according to the type of distribution. R3Startup Manager Property

Standalone distribution

SAP Unattended distribution

r3environment

No

Yes

Cluster Manager Property

Standalone distribution

SAP Unattended distribution

ClusterElementName OpenPort RepeatToConnect ClusterHosts

Dispatcher One 2055 False localhost\:2078; localhost\:2062; localhost\:2063; localhost\:2064; localhost\:2065 5001 2077 false

Dispatcher 01

ClusterElementId JoinPort Gateway

00 missing property

HTTP Service Property

Standalone distribution

SAP Unattended distribution

Port SslPort

80 443

09 08

4/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

HttpTunneling Service Property

Standalone distribution

SAP Unattended distribution

Port

3080

02

JMS Service Property

Standalone distribution

SAP Unattended distribution

/tcp

1149

03

Telnet Service Property

Standalone distribution

SAP Unattended distribution

Port

2323

04

Shell Service Property

Standalone distribution

SAP Unattended distribution

$SUBPROMPT $PROMPT

--> >

--> >

R3Startup Service Property

Standalone distribution

SAP Unattended distribution

element_0_id element__id

4001 ????

00

P4 Service Property

Standalone distribution

SAP Unattended distribution

Port Ssl httptunneling

3011 3044 3080

06 05 07

5/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

Monitor Service Property

Standalone distribution

SAP Unattended distribution

Port

3906

10

IIOP Service Property

Standalone distribution

SAP Unattended distribution

Port

3333

11

Server The following properties’ values differ, according to the type of distribution. R3Startup Manager Property

Standalone distribution

SAP Unattended distribution

r3environment

No

Yes

Cluster Manager Property

Standalone distribution

SAP Unattended distribution

ClusterElementName OpenPort RepeatToConnect ClusterHosts

Server One 2056 false localhost\:2077; localhost\:2062; localhost\:2063; localhost\:2064; localhost\:2065 4001 2078 false

Server 0 17 true :00

ClusterElementId JoinPort Gateway

Monitor Service

6/24

00 16 missing property

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

Property

Standalone distribution

SAP Unattended distribution

port

3907

18

Servlet_jsp Service Property

Standalone distribution

SAP Unattended distribution

ExternalCompiler

/bin/javac

javac

Shell Service Property

Standalone distribution

SAP Unattended distribution

$SUBPROMPT $PROMPT

--> >

--> >

Legend of Used Denotations General Denotations · · · · · · ·

CNAMEBIC – Cluster Name By Convention RTCBIC – Repeat To Connect By Convention HPBIC – Host and Port By Convention (:) DIDBIC – Dispatcher ID By Convention LHBIC – Local Host By Convention xxPORTBIC – Port offset By Convention xxSIDBIC – Server xx ID By Convention

Arguments Taken by TFReplace.class · · · · ·

-id – specifies the system id of the current box (the system id of the R/3 Instance) -bn – specifies a unique number for each box -mhost – specifies the host name or IP of the main box -mid – specifies the system id of the main box -pbase – specifies the ports number base. Default value is 30000

7/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

Calculation Formulas · · · · · · ·

CNAMEBIC = _ RTCBIC – if it is a main box, HPBIC – if it is a main box,

the value is true, otherwise false the value is :80 * mid + , otherwise the value is “” (empty) DIDBIC = 10000 * + 80 * + LHBIC = localhost xxPORTBIC = xx + 80 * + xxSIDBIC = 10000 * - 5000 + xx + 80 * +

Id Correspondence · · · · · · · · · · · · · · ·

dispatcher join port – xx = 00 dispatcher open port – xx = 01 Httptunneling – xx = 02 jms – xx = 03 telnet – xx = 04 p4 over ssl – xx = 05 p4 – xx = 06 p4 over http tunneling – xx = 07 http over ssl – xx = 08 http – xx = 09 monitor (dispatcher) – xx = 10 iiop – xx = 11 server join port – xx = 16 server open port – xx = 17 monitor (server) – xx = 18

Note: The next chapters of this document concern SAP Unattended installation, e.g. the integrated into R/3 version of SAP J2EE Engine.

8/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

R3Startup Manager. R3Startup Service Overview Starting SAP J2EE Engine from R/3 dispatcher, communication concerning the engine data transfer, as well as receiving and sending messages is performed in SAP J2EE Engine by r3Startup manager and r3Startup service. During startup the R/3 dispatcher reads the profile parameter rdisp/j2ee_server. If defined the value must be the startup command for SAP J2EE Engine dispatcher, which starts up and controls all services needed by SAP J2EE Engine. If the value is 1, the Web Application Server (WAS) dispatcher tries to start SAP J2EE Engine. The default value of this parameter is 0. Profile parameters Parameter

Description

Default Value

rdisp/start_j2ee

If the value is 1, the WAS dispatcher tries to start SAP J2EE Engine.

0

exe/j2ee

Executable or command to start server, in case of SAP J2EE Engine this is the command procedure go.sh or go.bat.

none

rdisp/j2ee_timeout

When the J2EE server is started, it has to connect within 60 seconds. If the server doesn’t connect, the WAS dispatcher assumes that the start failed, the process will be killed and restarted.

60 sec

rdisp/j2ee_error

Maximal number of failed starts before the start of the server is disabled. The start can be enabled again. If this number was exceeded the value of rdisp/start_j2ee is set to 0. To enable the start change this value dynamically to 1 with transaction RZ11. If the J2EE server connects successfully to the WAS dispatcher this error counter is set to 0.

10

9/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

WAS – SAP J2EE Communication For internal communications between WAS and SAP J2EE Engine dispatcher, a simple, extensible interface is used: · ·

· · ·

WAS binds a local TCP/IP socket; WAS 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= – the communication port between WAS and SAP J2EE Engine. o -DLISTEN_PORT= – the LCOM-communication port. o -DSAPSYSTEM=nn – a 2-digit system number, used for identification of the system resources needed by WAS. o -DSAPSYSTEMNAME= – a 3-digit system id used by WAS. o -DSAPMYNAME= – the application server name – the profile filename. o -DSAPPROFILE= If the connection to SAP J2EE Engine is lost, the server will be restarted. As soon as the J2EE server connects to the WAS 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. First four characters determine the message length, without counting these four characters. First Byte is the highest order byte and the last one, the lowest order byte. This encoding gives an integer representation regardless of the internal representation.

For communication between the R/3 dispatcher and the SAP J2EE Engine dispatcher a local TCP/IP network connection is established. The R/3 dispatcher binds a local port and passes the port number to the SAP J2EE Engine dispatcher via Java System Property. After initialization the SAP J2EE Engine dispatcher connects to this local port and the communication channel is established.

10/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

If the network connection is closed for any reasons, it is assumed that the SAP J2EE Engine dispatcher failed and the R/3 dispatcher tries to restart it.

Command Interface Commands: SAP J2EE Engine -> WAS: · · · · · · · · ·

PID=

processes.

– the java VM process id. Checks the SAP J2EE Engine

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 server (maximum 1000), i.e. a server with weighting factor 20 will get twice of requests as a server with 10. INVALIDATE_ETAG= – the message is forwarded to ICMan to invalidate the specified . INVALIDATE_URL= – the message is forwarded to ICMan to invalidate the specified . All other messages will be ignored

Commands: WAS ->SAP J2EE Engine: · · ·

HARDSHUTDOWN SOFTSHUTDOWN

– immediately stops SAP J2EE Engine; – stops SAP J2EE Engine after finishing all started

requests. All other messages will be ignored

Running SAP J2EE Engine in an R/3 Environment. Communication R3Startup Manager The r3Startup Manager function is to write in a log file the process identifications of a corresponding cluster element. By default the log file location is /tools/r3startup/clusterpids. To accomplish this function the r3Startup Manager uses a native method from a

11/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

library located in /tools/r3startup/logpid.dll. This function gives R/3 dispatcher an opportunity to stop the SAP J2EE Engine cluster, killing the processes of the started elements even in situations when dispatcher is not properly shutdown (it’s process has been killed without giving it the chance to stop the server it has started) and than has been started again. Besides, the r3Startup Manager running on SAP J2EE Engine dispatcher, opens a socket for communication on a port given by the R/3 dispatcher. The following properties concern integration. For more information, please consider Administration Manual. · ·

· · ·

r3environment PIDsLogFileName InfoLogFileName, NoticeLogFileName, DebugLogFileName CONNECT_PORT KILL_OLD_SERVER_PIDS

WarningLogFileName,

and

R3Startup Service The R/3Startup Service can be started only on SAP J2EE Engine dispatcher. This service establishes the connection with the R/3 dispatcher through the socket created by the r3Startup manager and holds up permanently running server elements (when one of the elements crashes, is restarted), specified in the /cluster/dispatcher/services/r3startup/properties file. The file format is: · ·

·

elements

– the number of elements that the service must run and

support. elements in format: elementXid – cluster ID of the element; elementXdir – a path to the element, where X is number of the subsequent cluster element that has to be. The first element number is “0”, which means that the names of its properties will element0name and element0dir. other properties – log files and timeout for soft shutdown.

12/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

The communication with the R/3 dispatcher is accomplished through a TCP/IP protocol and contains packages in UTF8 format with 4 byte headers, which contain information about the size of the text field. Each package contains one message and SAP J2EE Engine can send: · · · · · ·

HTTP_PORT=xxxx HTTPS_PORT=xxxx LB=xx ACTIVE INACTIVE NOOP

The last message can be sent in both directions. The other messages that the R/3 dispatcher sends are: · ·

HARDSHUTDOWN SOFTSHUTDOWN

There are four shell commands available in r3startup service: · · ·

SENDACTIVE – sends the ACTIVE message; SENDINACTIVE – sends the INACTIVE message; INVALIDATE_ETAG and INVALIDATE_URL – clears

ICMan cash.

Usage of Native Libraries for R/3 – SAP J2EE Engine Integration Native libraries are used to retrieve process IDs. This is not possible to be done with pure Java, because no means for dealing with process ids are provided in the 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 seeks 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 R/3 dispatcher. This is done so that the R/3 dispatcher could 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

13/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

period of time (this timeout is a property of R/3 dispatcher). R/3 dispatcher can also perform some life checks using the process ID. Native libraries are also used in server nodes for logging server process ids (default log file is /tools/r3startup/clusterpids). After that in cases when SAP J2EE Engine dispatcher node crashes without being able to stop server nodes, the next time it starts it kills the logged process ids if and only if the property KILL_OLD_SERVER_PIDS of R3StartupManager is set to Yes.

R3Startup Service Errors ID021000: No connection with R3 ID021001: A communication error has arisen ID021100: ID021101: ID021102: ID021103: ID021104: ID021105: ID021106: ID021107: ID021108:

Couldn't Couldn't Couldn't Couldn't Couldn't Couldn't Couldn't Couldn't Couldn't

send send send send send send send send send

NOOP to R/3 dispatcher INVALIDATE_ETAG to R/3 dispatcher INVALIDATE_URL to R/3 dispatcher ACTIVE to R/3 dispatcher INACTIVE to R/3 dispatcher LB to R/3 dispatcher HTTP_PORT to R/3 dispatcher HTTPS_PORT to R/3 dispatcher PID to R/3 dispatcher

ID021200: Couldn't start a server ID021201: Necessary service property is missing or invalid

14/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

Logging in SAP R/3 System using R3AccountLoginModule If the user fails to connect to the server a login to SAP R/3 System will be attempted (if such exists and the property files described later are correctly set). These are the steps the user must make to obtain the connection. All of them are obligatory. · ·

·

On the following address download SAP Java Connector (JCO): http://service.sap.com/connectors. The latest supported version of JCO is 2.0. Extract the downloaded ZIP file to an arbitrary directory. Add sapjcorfc.dll to the PATH system variable: sapjcorfc.dll In the script file named go, located in

/cluster/server or /alone/ set the library path variable to point to /sapjcorfs.dll by adding the following variable setting into the command line: -Djava.library.path="%PATH%";/sapjcorfc.dll

Using SAP R/3 LoginModule The integration requires SAP Basis R/3(Account)UserFactory, R/3AccountLoginModule implementation is provided by the jars tc_sec_core.jar and tc_sec_api.jar. They are using sapjco.jar. Also an IAIK implementation JAR named IAIK_jce is needed. The provider of the SAP J2EE Engine server must supply the user with it. All JAR files must be in/cluster/server/additionallib or /alone/additional-lib.

15/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

InQMy.config This configuration file is located in /cluster/server/services/security/work or /alone/services/security/work. Generated and maintained by Security Service. It can be manipulated only through the Visual Administrator. Do not change it manually. For information on using the Visual Administrator refer to Administration Manual -> Services Administration Reference -> Security Service -> Visual Administrator -> Runtime Control -> JAAS. This file contains the JAAS login modules for the different applications. Integration to SAP security roles requires R3AccountLoginModule to be added to the list of login modules for "InQMyLoginSystem". Adding it will require providing options for the login module as described in the documentation of R3AccountLoginModule. Example: InQMyLoginSystem { com.inqmy.services.security.jaas.InqmyLoginModule Sufficient; com.sap.security.um.r3.R3AccountLoginModule Sufficient loginlanguages = "DE, EN, FR" defaultlanguage = "2" lazyinitialisation = "1" createticket = "0" acceptticket = "1" acceptpassword = "1" useraccountfactory = "b6a" userfactory = "b6a"; }; other{ com.inqmy.system.SystemLoginModule required application=otherHelper ; };

The tags other are used for login through JAAS by an application. It can be used only if the first tab InQMyLoginSystem is empty. Another way of configuring remotely InQMy.config is by performing look up on RemoteSecurity and by using the method getRemoteJAASConfigurator() to configure the connection. For more information on RemoteSecurity methods refer to Development Manual –> Services Guide -> Security Service.

16/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

R3Security.properties This file must be created manually in the following directory: · ·

/clustter/server/services/security/work /alone/services/security/work.

Additional information about these properties in the files can be found on http://help.sap.com/ in SAP Library -> mySAP Technology Components -> SAP Web Application Server -> SAP J2EE Engine. The configuration properties in this file determine which SAP system the user factory operates in and the account of the server user. For more information on this refer to R3AccountLoginModule in SAP Security API. Example file: #Global security system configuration sapbasis.user = USER_NAME sapbasis.passwd = USER_PASSWORD sapbasis.client = 000 sapbasis.ashost = pwdf0260.wdf.sap-ag.de sapbasis.sysnr = 13 sapbasis.lang = DE sapbasis.acceptticket = 1 sapbasis.createticket = 0 userfactory.sapbasis = b6a useraccountfactory.class = com.sap.security.um.r3.R3UserFactory useraccountfactory.sapbasis = b6a userfactory.class = com.sap.security.um.r3.R3UserFactory userfactory.sapbasis = b6a userfactory.timezonemap=timezone.properti es useraccountfactory.timezonemap=timezone.p roperties

Timezone.properties Create this property file in an arbitrary directory and point it in R3Security.properties at the userfactory.timezonemap and useraccountfactory.timezonemap fields. The file must contain the following information:

17/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

#Time Zone Mapping File for R3UserFactory #Format: Java Time Zone ID = SAP Time Zone ID UTC = UTC MST = MST EST = EST WET = WET Pacific/Easter = CST Europe/Berlin = CET Africa/Cairo = EGYPT Asia/Tokyo = JAPAN America/Los_Angeles = PST Asia/Kabul = AFGHAN Australia/Hobart = AUSACT Europe/Moscow = RUS03 Pacific/Norfolk = NORFLK

The following test shows an attempt to login through R/3 System into SAP J2EE Engine: > add login > login USER_NAME USER_PASSWORD user: USER_NAME logged in successfully > sessions 1. USER_NAME SESSION_NUMBER DATE TIME > add user > parents USER_NAME PARENT_SECURITY_ROLE > logout user logged out successfully > sessions No users are logged at the moment > login USER_NAME OTHER_PASSWORD Authorization failed! Reason: ID001281: Access denied!

The above example settings are for B6A system for user USER_NAME. With these settings the server recognizes the users of B6A user management and the security roles of B6A as user groups of the server.

18/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

Note: To be able of viewing security roles of the users the property sapsystem must be added in the file Properties file. It is located in /cluster/server/services/security/. The value of this field in our case will be B6A: sapsystem = b6a, i.e. the sapbasis. Notice that: · ·

login with USER_NAME user creates a security session on the account; parent group of the user is the R/3 security role of the user.

The system treats the R/3 security roles as user groups. Note that in case the property sapsystem in Properties.file is set properly: ·

if the user does not have any security role the privileges of the group “external” will be granted;

19/24

Web Application Server – SAP J2EE Engine Integration

· · · ·

SAP J2EE Engine 6.20

there are user groups for each role of the R/3 system and they are located in "external" group; grouping any security role out of "external" user group will have no effect on permissions of either group; grouping any user in "external" user group will have no effect; R/3 users are not displayed in the user tree. They are represented by their security roles.

Now, mapping to J2EE roles is done as with ordinary user groups:

After logging in successfully, the user will be added to the “external” group and in this way accesses the server resources. Examples on configuring the R3Properties.properties and InQMy.config files are available in docs/examples/sap_r3.

20/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

ICMan – SAP J2EE Engine Communication The integration of SAP J2EE Engine into SAP Web Application Server(WAS) is realized through ICMan acting as a web server. Client

ICM XML/SOAP

Business Server Pages

JSP / Servlets

RFC

JCo HTTP

Session Beans Entity Beans

Business Objects

SAP Web Application Server Architecture

The communication (data transfer) between ICMan and SAP J2EE Engine is done via a TCP/IP-based network connection. The communication with SAP Business Server Page Engine (BSP) is done via Memory Pipes (MPI). The communication protocol between ICMan and SAP J2EE Engine provides: ·

minimized network overhead: o connections are reused for other requests (connection pool) o small (fixed size) protocol header

21/24

Web Application Server – SAP J2EE Engine Integration

· ·

SAP J2EE Engine 6.20

copy free transfer of the HTTP-request from the network to SAP J2EE Engine and copy free transfer of the response from SAP J2EE Engine to the client (e.g. browser). compatibility and extensibility (for further enhancement)

Connection handling The network connections are established by ICMan to SAP J2EE Engine (listening port is known to ICMan) and are managed in a connection pool. ICMan may open further connections on heavy load and/or close connections when they are not used. To avoid the time consuming establishment of new network connections the connection between ICMan and SAP J2EE Engine should be kept open over several request/response cycles. The lifetime of the network connection is not bound to the underlying protocol (e.g. HTTP connection-header) but one connection is exclusively reserved for one request/response cycle at a time. For protocol simplicity no multiplexing of requests take place on one network connection (parallel requests are dispatched to several network connections). SAP J2EE Engine must only close the connection in case of severe errors. ICMan closes a network connection to the server: · · ·

if the connection is considered superfluous by ICMan if SAP J2EE Engine has warned for a severe error at shutdown

Data flow Each request and response (one message) is defined by one or more communication blocks.

22/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

Headerlength1

Header1

Bodylength1

Body1

Headerlengthn

Headern

Bodylengthn

Bodyn

Communication blocks

Several communication blocks of one message (request or response) can be queued on the network. So the processes can forward data to their partners even if the overall size of the message is unknown (streaming support). The last block of one message is identified by the header field status = EOD (6).

23/24

Web Application Server – SAP J2EE Engine Integration

SAP J2EE Engine 6.20

SSL Requests On how to set SSL over HTTP, please consider Development Manual -> Services Guide -> Security Service, and Administration Manual -> Configuration Tasks -> Managing Security. SSL requests are identified by the header field protocol (protocol = 2). If the user supplies a client certificate for authentication the binary certificate is send to the server in the first communication block (body_type = 1). The HTTPrequest (header and body) is sent in the forthcoming communication blocks.

24/24