Administering the Java RPC Server

The EntireX Java RPC Server allows standard RPC clients to communicate with servers written in Java. It works together with the Java Wrapper and calls Java server interface objects. This document covers the following topics:

Customizing the RPC Server
Configuring the RPC Server
Using SSL/TLS with the RPC Server
Starting the RPC Server
Stopping the RPC Server
Running the RPC Server as a Windows Service
Application Identification

Customizing the RPC Server

The following elements are used for setting up the Java RPC Server:

Start Script
Properties File

Start Script

The start script for the Java RPC Server is called jrpcserver.bsh (UNIX) or jrpcserver.bat (Windows) and is provided in the bin folder of the installation directory. You may customize this file.

You can set the environment variable JAVA_HOME for the location of the Java interpreter. Set the classpath to entirex.jar and the path to the Java server interface objects.

The script files that start the Java RPC Server allow you to pass properties as command-line options as described in the table below. Alternatively, you can use system properties or a property file. The command-line option has the highest priority; the system property has second priority, and the entries of a property file have third priority.

Example:

java -Dentirex.server.properties=rpcserver.properties -classpath <entirex.jar with path>:<path to your server
interface objects> com.softwareag.entirex.aci.RPCServer

Properties File

The default name of the properties file is entirex.server.properties. The file is searched for in the directory of the Start Script. It can be changed by assigning an arbitrary file name with a path to a property with the name entirex.server.properties.

A sample properties file is contained in subfolder config of the installation folder.

Configuring the RPC Server

Property Name Command-line Option Default Explanation

entirex.rpcserver.packagename.library_name

The Java RPC Server can handle server programs with package names if the package name of each IDL library (see library-definition) is configured in the properties of the server. For each library the property entirex.rpcserver.packagename.library_name has the value of the package.

Example for the library Example (as in example.idl):

entirex.rpcserver.packagename.example=my.package

The library name must be lowercase. A package name can be specified when the server is generated. See Preferences and Properties under Using the Java Wrapper.

entirex.server.brokerid -broker localhost Broker ID

entirex.server.codepage

-codepage

EntireX Java components use the encoding configured for the Java virtual machine (JVM) to convert the Unicode (UTF-16) representation within Java to the multibyte or single-byte encoding sent to or received from the broker by default. This encoding is also transferred as the codepage (locale string) to the broker to tell the broker the encoding of the data. Depending on the internationalization approach, the codepage (locale string) is used by the broker. For the most popular internationalization approach, ICU Conversion, the correct codepage (locale string) must be provided. This means it must:

follow the rules described under Locale String Mapping
be a codepage supported by the broker
be a codepage supported by your JVM. For a list of valid encodings, see Supported Encodings in your Java documentation.

If these rules are not observed, unpredictable results may occur. With the codepage parameter you can override the encoding used to convert the Unicode (UTF-16) representation within Java to the multibyte or single-byte encoding sent to or received from the broker without the need to change the default encoding of the JVM.

Changing the default encoding of the JVM has the side effect the encoding for terminal and file IO is affected. This may be undesired. For how to change the default encoding of the JVM, see your JVM documentation. On some JVM implementations, it can be changed with the file.encoding property.

entirex.server.compresslevel

-compresslevel

0 (no compression)

Permitted values (you can enter the text or the numeric value):
`BEST_COMPRESSION`	`9`
`BEST_SPEED`	`1`
`DEFAULT_COMPRESSION`	`-1`, mapped to `6`
`DEFLATED`	`8`
`NO_COMPRESSION`	`0`
`N`	`0`
`Y`	`8`

entirex.server.customclass -customclass This class is used for custom initialization and shutdown of the server. In addition, this class allows handling when closing a conversation and handling the termination of a worker thread. See ServerImplementation for more information.

entirex.server.environment Can be used in a user-written translation exit of the Broker. See BrokerService, setEnvironment(java.lang.String) (EntireX Java ACI).

entirex.server.fixedservers no If no, use attach thread to manage worker threads; see SCALE. Otherwise run a fixed number of worker threads; see FIXED.

-help Display usage of the command-line parameters.

entirex.server.logfile -logfile Path and name of the trace output file. Environment variables in the name are resolved only if used as command-line option.

entirex.server.maxservers 32 Maximum number of worker threads.

entirex.server.minservers 1 Minimum number of server threads.

entirex.server.name The name of the server.

entirex.server.password -password yes The password for secured access to the Broker. The password is encrypted and written to the property entirex.server.password.e.
To change the password, set the new password in the properties file (default is entirex.server.properties).
To disable password encryption, set entirex.server.passwordencrypt=no.

entirex.server.properties -propertyfile entirex.server.properties The name of the property file.

entirex.server.restartcycles -restartcycles 15 Number of restart attempts if the Broker is not available. This can be used to keep the Java RPC Server running while the Broker is down for a short time.

entirex.server.security -security no no/yes/auto/Name of BrokerSecurity object.

entirex.server.serveraddress -server RPC/SRV1/CALLNAT Server address

entirex.server.serverlog -serverlog Name of the file where start and stop of worker threads is logged. Used by the Windows RPC Service.

entirex.server.userid -user JavaServer The user ID for the Broker for RPC. See entirex.server.password.

entirex.server.verbose -verbose no Verbose output to standard output yes/no.

entirex.server.waitattach 600S Wait timeout for the attach server thread.

entirex.server.waitserver 300S Wait timeout for the worker threads.

entirex.timeout 20 TCP/IP transport timeout. See Setting the Transport Timeout under Writing Advanced Applications - EntireX Java ACI.

entirex.trace -trace 0 Trace level (1,2,3).

Using SSL/TLS with the RPC Server

RPC servers can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium. The term "SSL" in this section refers to both SSL and TLS. RPC-based servers are always SSL clients. The SSL server can be either the EntireX Broker or Broker SSL Agent. For an introduction see SSL/TLS and Certificates with EntireX in the EntireX Security documentation.

Start of instruction set To use SSL

To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Set up the Java RPC Server for an SSL connection.

Use the URL-style Broker ID with protocol ssl:// for the Broker ID. If no port number is specified, port 1958 is used as default. Example:
```
ssl://localhost:22101?trust_store=C:\SoftwareAG\EntireX\etc\ExxCACert.jks?verify_server=no
```
If the SSL client checks the validity of the SSL server only, this is known as one-way SSL. The mandatory trust_store parameter specifies the file name of a keystore that must contain the list of trusted certificate authorities for the certificate of the SSL server. By default a check is made that the certificate of the SSL server is issued for the hostname specified in the Broker ID. The common name of the subject entry in the server's certificate is checked against the hostname. If they do not match, the connection will be refused. You can disable this check with SSL parameter verify_server=no.

If the SSL server additionally checks the identity of the SSL client, this is known as two-way SSL. In this case the SSL server requests a client certificate (the parameter verify_client=yes is defined in the configuration of the SSL server). Two additional SSL parameters must be specified on the SSL client side: key_store and key_passwd. This keystore must contain the private key of the SSL client. The password that protects the private key is specified with key_passwd.

The ampersand (&) character cannot appear in the password.

SSL parameters are separated by ampersand (&). See also SSL/TLS Parameters for SSL Clients.
Make sure the SSL server to which the Java RPC Server connects is prepared for SSL connections as well. The SSL server can be EntireX Broker or Broker SSL Agent. See:
- Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows | z/VSE
- Settting up and Administering the EntireX Broker SSL Agent under UNIX | Windows

Starting the RPC Server

Start of instruction set To start the Java RPC Server

Use the Start Script.

Or:
At the command prompt, enter:
```
java com.softwareag.entirex.aci.RPCServer
```

You can pass command-line options and customize your environment as described under Start Script.

Stopping the RPC Server

Start of instruction set To stop the Java RPC Server

Use the command stopServer. See Stop EntireX Broker Server Instances in Command Central's Command-line Interface.

Or:
Stop the server instance using Command Central's Graphical User Interface. See Stopping a Server Instance.

Or:
Use the command stopService. See Stop Running EntireX Broker Services in Command Central's Command-line Interface.

Or:
Stop the service using Command Central's Graphical User Interface. See Stopping a Service.

Or:
Use the command-line utility etbcmd. See etbcmd under z/OS | UNIX | Windows | z/VSE | BS2000.

Or:
Use CTRL-C in the session where you started the RPC server instance.

Or:
Under UNIX, enter command kill -process-id.

Running the RPC Server as a Windows Service

For general information see Running an EntireX RPC Server as a Windows Service.

Start of instruction set To run the Java RPC Server as a Windows Service

Customize the Start Script according to your system installation.
Note:
The script file must pass external parameters to the RPC server and use the reduced signalling of the JVM (option -Xrs):
```
java -Xrs com.softwareag.entirex.aci.RPCServer %*
```
If -Xrs is not used, the JVM stops and an entry 10164002 is written to the event log when the user logs off from Windows.
See also Starting the RPC Server.
Test your RPC server to see whether it will start if you run your script file.
Use the EntireX RPC Service Tool and install the RPCService with some meaningful extension, for example MyServer. If your Start Script is jrpcserver.bat, the command will be
```
RPCService -install -ext MyServer -script install_path\EntireX\bin\jrpcserver.bat
```
The log file will be called RPCservice_MyServer.log.
In Windows Services menu (Control Panel > Administrative Tools > Services) select the service: Software AG EntireX RPC Service [MyServer] and change the property Startup Type from "Manual" to "Automatic".

Application Identification

The application identification is sent from the RPC server to the Broker. It is visible with Broker Command and Info Services.

The identification consists of four parts: name, node, type, and version. These four parts are sent with each Broker call and are visible in the trace information.

For the Java RPC Server these values are:

Identification Part	Value
Application name	`ANAME=Java RPC Server`
Node name	`ANODE=host_name`
Application type	`ATYPE=Java`
Version	`AVERS=9.12.0.0`