(SM-2305) Java Connector Setup

Owned by SNP
May 17, 2023
15 min read

Java connector is a component used for authentication and communication with remote services using JDBC drivers or Java SDKs. It runs as an independent OS process and can be configured and controlled through transaction /DVD/JCO_MNG.

In this section:

 

/DVD/JCO_MNG allows you to link the Java connector (JCO) with the SAP RFC destination which will be used as a communication channel between SAP and JCO and maintain the connector. It also allows you to monitor standalone JCOs on the monitor screen.

Table of Contents:

Monitor Standalone JCO

To monitor standalone JCO RFC destination needs to be added to the monitor. This can be done by clicking the Connect Standalone JCO button in the toolbar. After the RFC destination is added, it is visible on the monitor. Note that in the monitor screen, standalone JCO can be only stopped but local JCO can be also restarted. To remove RFC from the monitor simply click the Remove RFC button in the ALV toolbar.

Deploying Java connector locally

To deploy local JCO switch to the local screen by clicking the Deploy local JCO button in the toolbar.

By default, the Java connector is deployed directly on the SAP ABAP application server and can be managed from the SAP Gui. If the operating system of the application server is Linux x64 or Windows x64, the setup is very straightforward. If you are using another operating system or architecture, follow additional steps in Using custom Java Runtime.

SAP RFC role and user

Java connector uses a dedicated user in the SAP system for registration on the SAP gateway and further communication between ABAP and Java.
This user should be created with the type System and with authorizations limiting his privileges to basic RFC communication.

Pre-created role /DVD/JCORFC is included with the software and can be used as is, or as a template for the custom role.

The required authorization object is S_RFC with these settings:

  • ACTVT = 16

  • RFC_NAME = RFC1, RFC_METADATA, SDIFRUNTIME, SYST

  • RFC_TYPE = FUGR

Java Connector RFC

Java Connector RFC is used to reference the Java service registered on the SAP gateway. Use the template below as a reference.

Settings:

  • Connection Type: T for TCP/IP Connection

  • Activation Type: Select Registered Server Program

  • Program ID: Name of the program how JCO will identify itself when logged on to SAP gateway (Example: DATAVARD_JAVA_CONN)

SAP Gateway Access

External communication with the SAP system goes through the SAP gateway. If the SAP system parameter gw/acl_mode is enabled, there are files reginfo that limit the access of external programs.
In this case, a program needs to have granted access either by wildcard definition or by explicitly defining the program registration name (in our example it is DATAVARD_JAVA_CONN).

More information on the SAP gateway ACL topic can be found on the SAP website Gateway Security Files secinfo and reginfo.

/DVD/JCO_MNG initial setup

  1. Select the latest JCO version by double-clicking the row on the left side of the screen.

  2. Switch to Edit mode.

  3. Click Fill default values.

  4. Fill in RFC Destination in the General tab.

  5. Fill in Technical user Credentials in the Config tab.
    Optionally, customize the Install directory. Logical path </DVD/DEF_JCO_DIR> translates to /usr/sap/<SID>/<instance_dir>/work/dvd_conn/.
    If multiple application servers are used, the installation directory must contain </DVD/DEF_JCO_DIR> to enable deployment to the appropriate path containing the INSTANCE directory on each app. server.

     

  6. Select the latest library in Libraries.

     

  7. Go back to the General tab, Save, and click Restart to deploy the Java connector.

     

In a scenario with multiple SAP application servers, the initial deployment needs to be done locally on each app. server. Switch to the respective app. server using transaction SM51.

 

Advanced parameters description

  • OS Command for starting Java service: Name of an OS command for starting Java service (SM69).

  • OS Command for setting access permissions: Name of an OS command for setting execution rights (SM69).

  • OS Command for 7Zip: Name of an OS command for unpacking libraries and embedded JRE (only if embedded JRE is chosen) (SM69).

  • Max RAM used: Maximum amount of RAM used by Java service (heap size).

  • Additional Java starting arguments: Additional arguments used to start the Java service.

  • Repository destination: Client destination from which repository should be obtained.

  • Work thread MIN: Number of threads Java service always runs with.

  • Work thread MAX: Maximum number of threads that can be used by the Java service.

  • Connection count: Number of connections registered at SAP gateway. Maximum number of connections per JCO instance is 100.

  • Peak limit: Limit of JCo connections at peak.

  • Log4j log level: Level of messages collected in logs.

  • Log4j log deletion: Log retention period.

  • Log files path: Directory where the log files will be saved.

  • JAR path: Path where the JCO JAR file will be created.

  • Log4j config path: Path where the log4j config file will be created.

  • Server config path: Path where the server config will be created.

  • Destination config path: Path where the destination config will be created.

  • Avoid JCO config files creation: Special option which prevents automatic overwriting of existing JCO files. Useful for cases when manual modification of configuration files is needed (troubleshooting).

  • Use JCO dir for parquet conversion: If required, JCO performs data conversion into PARQUET format. This is by default done in memory; when this option is active, conversion is done using temporary files in JCO_install_dir/parquet subdirectory. This may be necessary if the memory allowance for JCO is limited.

  • Embedded JRE: Path to embedded JRE (nested in Install directory in Config Tab (JCO_HOME)).

  • Use custom JRE: Checkbox whether or not to use custom JRE for JCo, if checkbox is not checked, then embedded JRE is used.

  • Custom JRE: Path to custom JRE (can be nested in Install directory in Config Tab (JCO_HOME), or anywhere on the system).                

The Java service is started with a system command. You can adjust the name of this command in the table Advanced tab. The default name of the command is ZDVD_START_JAVA. In the case the system command doesn't exist, it is created automatically. You can view the system commands through the transaction SM69. On Linux, another system command is required, which sets executable rights for the configuration files (chmod 755 <filename>). Its name can be adjusted in the Advanced tab.

Using custom Java Runtime

As of version Reuse Library 22.08, the SNP Java connector comes with regularly updated embedded Java runtime (Adoptium 11) for Linux 86_x64 and Windows x64 and no manual setup is required in this regard.

If you have another operating system (Solaris, AIX, etc.), or you cannot use embedded JRE for any reason, you will need to deploy your Java runtime and libsapjco3 libraries manually.

Java runtime environment (JRE)

Recommended JRE is OpenJDK 11, but generally, the recent releases of Java 8 are usable. OpenJDK can be downloaded from the Adoptium download site for most architectures.

Not to interfere with possible Java installation already present on the SAP application server, the archive can be simply unpacked into any directory accessible to <sid>adm, e.g. /sapmnt/<SID>/global/JRE_11/.

The option to choose between embedded JRE and custom JRE can be found in the Advanced Tab of /DVD/JCO_MNG transaction:

Parameters:

  • Embedded JRE: Path to embedded JRE Java binary. It is by default nested in the Install directory defined in Config Tab (JCO_HOME).

  • Use custom JRE: Checkbox whether or not to use custom JRE. In the default configuration, the checkbox is unchecked, so embedded JRE will be deployed and there is no need to specify Custom JRE.

  • Custom JRE: Path to custom JRE Java binary. This option is usually needed on non-standard operating systems (see information below).

SAP Java Connector Library

Java Connector uses a shared library published by SAP named libsapjco3.so (or sapjco3.dll on Windows OS).
Starting with SNP JCo version 229, the library is included in SNP transports for Linux 86_x64 and Windows x64.
If the system hosting JCo is running on OS other than Linux 86_x64 and Windows x64, it is necessary to manually download and replace the library after the first attempt to start the JCo.
The first start attempt will fail due to incompatibility, but it will deploy all other libraries and configuration files needed for the JCo run. The location of the libraries is /<installation_directory_path>/lib/.

SAP Java connector library can be downloaded at SAP Java Connector.

Once uploaded to the JCo host, after the first startup attempt (see below), simply replace the library and change the ownership to <sid>adm:sapsys, for example:

cp libsapjco3.so /usr/sap/NSD/DVEBMGS01/work/dvd_conn/jco233/lib/ chown nsdadm:sapsys /usr/sap/NSD/DVEBMGS01/work/dvd_conn/jco233/lib/libsapjco3.so

Central Java instance

It is possible to have a single Java connector running, instead of running one on every application server. To set such a scenario, follow these steps:

  1. If the Java connector is already running on several application servers, stop all instances.

  2. Open the Java RFC destination and fill in the Gateway options valid for the desired instance.

     

  3. When you restart the transaction /DVD/JCO_MNG, only buttons belonging to the desired application server should be functional and all the other app. servers should be using this connection.
    Start the connector and all rows in the Connection column should be green.

     

Setting up the connection via the proxy server

Sometimes communication with a service outside the corporate network needs to be routed through a proxy server to comply with company security standards.

To achieve this, you need to add the following Java parameters to the Additional Java starting arguments field in the Advanced tab of /DVD/JCO_MNG.

-Dhttps.useProxy=true -Dhttps.proxyHost=<proxy_host> -Dhttps.proxyPort=<proxy_port>

SNC configuration

If the SAP system is hardened by enabled Secured Network Communication (system parameter snc/enable = 1), there are additional configuration steps.

  1. The first step is the creation of a Personal Security Environment (PSE) for JCo. This is to be done under <sid>adm user. PSE should be stored together with other SAP PSE files, by default on path /usr/sap/<SID>/<SAP_instance>/sec, referenced by the environment variable $SECUDIR. Commands to create the PSE, with an example of system ID NSZ with csh as nszadm’s shell:
    su - nszadm
    setenv SECUDIR /usr/sap/NSZ/D00/sec
    cd $SECUDIR
    sapgenpse gen_pse -v -p DVDJCO.pse

    A passphrase can optionally protect PSE. The mandatory input parameter is the Distinguished name of the PSE owner, in our example, it’s CN=JCO_RFC, OU=DVD, C=DE

    nsz:nszadm 98> sapgenpse gen_pse -v -p DVDJCO.pse Got absolute PSE path "/usr/sap/NSZ/D00/sec/DVDJCO.pse". Please enter PSE PIN/Passphrase: Please reenter PSE PIN/Passphrase: !!! WARNING: For security reasons it is recommended to use a PIN/passphrase !!! WARNING: which is at least 8 characters long and contains characters in !!! WARNING: upper and lower case, numbers and non-alphanumeric symbols. get_pse: Distinguished name of PSE owner: CN=JCO_RFC, OU=DVD, C=DE Supplied distinguished name: "CN=JCO_RFC, OU=DVD, C=DE" Creating PSE with format v2 (default) succeeded. certificate creation... ok PSE update... ok PKRoot... ok Generating certificate request... ok. Certificate Request: Signed Part: Subject: CN=JCO_RFC, OU=DVD, C=DE Key: rsaEncryption (2048 bits) Attributes: None Signature: Signature algorithm: sha256WithRsaEncryption (1.2.840.113549.1.1.11) Signature: <Not displayed> PKCS#10 certificate request for "/usr/sap/NSZ/D00/sec/DVDJCO.pse": -----BEGIN CERTIFICATE REQUEST----- MIICcjCCAVoCAQAwLTELMAkGA1UEBhMCREUxDDAKBgNVBAsTA0RWRDEQMA4GA1UE ################################################################ ################################################################ ################################################################ PxmDNQSCYvLxURXcP+vQxDSOq5QYgQf4g4egjVXRcyQwOJNZRpHlP1olXc4Aa675 -----END CERTIFICATE REQUEST----- nsz:nszadm 99>

     

  2. The second step is to export the certificate with the public key from the newly created PSE, using the command:
    sapgenpse export_own_cert -v -p DVDJCO.pse -o DVDJCO.crt
    This produces a DVDJCO.crt file.

     

  3. Now import the DVD JCo certificate file into the SAP system’s Trust manager.
    Run transaction STRUST > switch to Edit mode > double-click SNC PSE node > in the lower part of the screen click on the Import certificate icon, locate the certificate file, confirm file selection > click Add to Certificate List > Save (Ctrl+S)
    NOTE: You may need to download the certificate file to your front end to be able to select it.

  4. We have imported the JCo certificate to SAP. To create two-way trust between SAP and JCo, we now need to import the SAP system’s certificate to JCo PSE.
    Export SAP’s certificate, similarly as in step 3. Run STRUST and select the SNC PSE node, but double-click on Own certificate, and at the bottom of the screen click the icon Export certificate. Choose Base64 format, path, and filename to save the .crt file. Upload the file to the application server, ideally to $SECUDIR.

  5. To import the SAP certificate to JCo PSE, run the command:
    sapgenpse maintain_pk -v -a SAP.crt -p DVDJCO.pse

     

  6. To allow JCo to run under <sid>adm user using the credentials stored in the PSE, SSO credentials must be created in the cred_v2 file.
    It is advised to back up the cred_v2 file before proceeding.
    The file should already exist in SECUDIR and will be updated using the command:
    sapgenpse seclogin -p DVDJCO.pse -O nszadm


    NOTE: If JCO is deployed in a Windows environment, allow access to the PSE file also for user SAPService<SID>.
    example: sapgenpse seclogin -p DVDJCO.pse -O SAPServiceNSZ

    Available SSO credentials can always be checked using the command:
    sapgenpse seclogin -l

  7. Now that the security environment is prepared, configure JCo SNC in transaction /DVD/JCO_MNG in the Config Tab:

     

    • SNC enabled: Once activated, user and password fields will be greyed out and have no effect on JCo configuration.

    • SNC QoP Level: SNC Quality of Protection, needs to be the same level as set in system parameter snc/data_protection/use (default = 3).

    • JCo SNC name: Distinguished name chosen during the creation of JCo PSE (step 1).

    • SNC-enabled GW port: SAP gateway port used for secure communication. The port number is 48$$, $$ being the instance number of a particular application server.

    • SNC partner name: Distinguished name of SAP system, pre-filled from SAP profile parameter snc/identity/as.

      Save the configuration when completed, but do not start the JCo yet.

  8. There are two more configuration pieces to complete before JCo can properly start and register on the SAP gateway.
    In SU01, activate SNC for RFC user dedicated to JCo communication, filling SNC name dedicated to JCo.
    Despite the user no longer being configured in /DVD/JCO_MNG, it is used by matching the SNC name entered here and the Distinguished name configured in JCo PSE.


    Secondly, via SM59 activate SNC in the RFC destination dedicated to communication between SAP and JCo and fill JCo Distinguished name again in the Logon & Security tab (SNC options button):


    Having all SNC prerequisites met, Java Connector can be started.

Sample JCo configuration files with SNC enabled

Upgrading Java connector

This is a list of steps to do when you update your SNP software and you would like to switch to a new version of the Java connector.

  1. Open transaction /DVD/JCO_MNG

     

  2. Double-click the current working connector and click Stop all.

  3. After the current version of the SNP Java connector is disconnected, click Copy config.

     

  4. Double-click the new version of the connector, enter Edit mode, then click Paste config, then fill the RFC Usage field with the same RFC that was used with the old connector.

     

  5. Switch to the Config tab and adjust the Install directory to match the current ID of SNP Java Connector and click on Generate paths button.

  6. Switch to the Libraries tab and make sure you are using the latest libraries for your connector.

  7. Switch back to the General tab and click Restart for every Application server.
    It is important to start each JCO instance being logged onto the respective application server (SM51) to make sure the directories, libraries, and configuration files are deployed locally.
    This requirement is valid only for initial deployment, later operation (Stop/Start) is possible remotely, from any application server.

     

Copying Java connector

Sometimes it may be needed to COPY the JCo instance and create a version from it. When JCo is copied, the separate JCO_HOME directory is used and above the new JCO_HOME, the JRE process is started. Therefore new JCo has its own space for configuration and logs.

Possible use cases for JCo COPY:

  • Vertical scaling: When needed more JCo instances (JRE processes and each can handle different tasks/storage).

  • Versioning: When needed version of JCo for a different purpose.

  • JCo testing: To make different instances for testing and concern separation.

  1. Open transaction /DVD/JCO_MNG.

2. Click on Copy JCO.

  • Copy config from Java RFC: Copies JCo configuration from given RFC.

  • Copy config from version ID: Copies JCo configuration from given JCo ID.

  • Use default values: Use defaults.

  • Java version: Read-only field as a newly created copy of JCo will be created from the given Java version.

  • Description: Description of a newly created copy of JCo.

3. Newly created copy of JCo.

By default, it has adjusted JCO_HOME (Install directory) and all relevant settings in Advanced Tab to point to the new JCO_HOME (233.1)

4. Set RFC to the new JCo instance.

Go to the General tab and assign the RFC to the Java connector.