Administering the XML/SOAP RPC Server

The XML/SOAP RPC Server allows RPC clients to communicate with target servers via HTTP(S). The XML/SOAP RPC Server transforms RPC client calls into XML/SOAP calls. It works together with the XML/SOAP Wrapper. This document covers the following topics:

Customizing the RPC Server

The following elements are used to set up the XML/SOAP RPC Server:

Start Script

The start script for the XML/SOAP RPC Server is called jxmlrpcserver.bsh (UNIX) or jxmlrpcserver.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 generated proxies.

The XML/SOAP RPC Server accepts two unnamed parameters, broker_id and server_address. Default values are localhost:1971 and RPC/SRV/CALLNAT. Example: 

java com.softwareag.entirex.xml.rt.XMLRPCServer broker_id server_address

Properties File

The default name of the properties file is entirex.xmlrpcserver.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.xmlrpcserver.propertyfile.

The following is a sample properties file entirex.xmlrpcserver.properties: 

# Example server configuration
#
# parameter for xml stream parser
entirex.sdk.xml.runtime.xmlparserfactory=com.ctc.wstx.stax.WstxInputFactory
# xmlruntime configuration file
entirex.sdk.xml.runtime.configurationfile=entirex.xmlrpcserver.configuration.xml
#
# Basic properties
entirex.server.brokerid=localhost
entirex.server.serveraddress=RPC/XMLSERVER/CALLNAT
entirex.server.userid=XMLRPCServer

It can define parser settings, for example JAXP parameters (optional if these parameters are already specified in your environment) and the location of the configuration file. A sample properties file is contained in subfolder config of the installation folder.

System Properties

Additionally, Java system properties are available to administer the XML/SOAP RPC Server. These properties are independent of the administration possibilities listed above.

Java System Property Description Values Default
http.keepAlive Enable/disable HTTP persistence true, false true
http.maxConnections Define the maximum number of HTTP connections to a host.

Note:
Requires http.keepAlive=true

 Integer > 0 5
http.maxTotalConnections Define the maximum total number of HTTP connections to a host.

If http.maxConnections is greater than http.maxTotalConnections, this value is set to value of http.maxConnections.

Note:
Requires http.keepAlive=true

 Integer > 0 20

Configuration File

The configuration contains a list of target servers defined in the TargetServer block, including XML mapping files (XMM) associated with them and may contain information about the broker if not already given as a property (command-line option, system property or property file).

The default name of the configuration file is entirex.xmlrpcserver.configuration.xml. 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.xml.runtime.configurationfile.

The configuration file has the lowest priority. It is written in XML format. The document frame is:

<?xml version="1.0" encoding="UTF-8" ?> 
<EntireX xmlns="http://namespaces.softwareag.com/entirex/xml/runtime/configuration" version="9.12.0" >
      <XmlRuntime Version="1">
      <!-- information for XML/SOAP RPC Server, see TargetServer Block -->
      </XmlRuntime>
</EntireX>

Configuring the RPC Server

The XML/SOAP RPC Server uses the properties that start with "entirex.server" for configuring the RPC server side.

Alternatively to the properties, you can use the command-line options. These have a higher priority than the properties set as Java system properties, and these have higher priority than the properties in the configuration file.

Property Name Command-line Option Default Explanation
entirex.server.brokerid -broker localhost Broker ID
entirex.server.codepage -codepage   The codepage the server uses. Permitted values are the names of the codepages the JVM supports. Use the value LOCAL when the default codepage of the JVM should be used. See Using Internationalization with EntireX XML Components under Writing Advanced Applications with the XML/SOAP Wrapper for details.
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 8
DEFLATED 8
NO_COMPRESSION 0
N 0
Y 8
 
entirex.server.development.relativepaths   false The file locations of deployed XMM and WSDL files are written as relative paths in configuration file of the XML/SOAP RPC Server.
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 server to manage worker threads, otherwise run minimum number of server threads.
entirex.server.ignoreSOAPActionNamespace   false true: Only the name part of SOAPAction is used, the namespace is ignored.
false: The SOAPAction value is used as defined.

Note:
If a WSDL file is configured for this method, the property will be ignored and SOAPAction value defined in WSDL is used.

  -help   Display usage of the command-line parameters.
entirex.server.logfile -logfile   Name of the log file, default is standard output. Environment variables in the name are resolved only if used as a 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   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. Default for this property is yes.
entirex.sdk.xml.runtime.propertyfile -propertyfile entirex.xmlrpcserver.properties The file name of the property file.
entirex.sdk.xml.runtime.configurationfile -configurationfile entirex.xmlrpcserver.configuration.xml Location and name of configuration file.
entirex.server.restartcycles -restartcycles 15 Number of restart attempts if the Broker is not available. This can be used to keep the XML/SOAP 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 Enable verbose output to the log file.
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).
entirex.sdk.xml.runtime.xmlparserfactory -jaxp.saxparserfactory com.ctc.wstx.stax.WstxInputFactory Location and name of stream parser factory class.
entirex.sdk.xml.runtime.
defaultFaultDocumentFormat		   soap Define the protocol used for fault document generation if no fault document is defined. Defined values = soap, xml.

Using SOAP 1.2 with the RPC Server

Generated Mapping (XMM)

Generate a new XML mapping file with SOAP mapping in the XML Mapping Editor, or use an existing one.

Note:
Do not change the namespace for SOAP. This must be the namespace for SOAP version 1.1.

Configure XMM

To use SOAP 1.2 for an XMM file, add the attribute soapVersion to section xmms in element exx-xmm in the configuration file. See soapVersion under TargetServer Block below for details.

Locating and Calling the Target Server

The IDL library and IDL program names that come from the RPC client are used to locate the target server. See library-definition and program-definition under Software AG IDL Grammar in the IDL Editor documentation. This two-level concept (library and program) is mapped to a target servers using an XML mapping file (XMM) together with connection information. Both connection information and XML mapping files are defined in the target server block of the Configuration File.

Mapping Software AG IDL files to XML/SOAP is described under XML Structures and IDL-XML Mapping in the XML/SOAP Wrapper documentation. This section describes the following elements to define servers:

TargetServer Block

The section <TargetServer> specifies a target server with mandatory HTTP(S) Web service address in the name attribute.

Tip:
If you are using a target located outside the firewall, set the following Java properties:

  • http.proxyHost

  • http.proxyPort

  • http.nonProxyHosts

  • http.proxyUser

  • http.proxyPassword

Configuring SSL/TLS to the target server is described under Using SSL/TLS with the RPC Server.

The block contains section <xmms> with EntireX XML mapping files (XMM files). Each <TargetServer> entry can have a list of XMMs for its server.

Caution:
It is not allowed to use one XMM in more than one TargetServer entry inside one configuration file.

Within the <TargetServer> tag you can specify basic authentication with a fixed user/password:

Attribute Req/
Opt 		Description
basicAuthentication O
true Activate the basic authentication.
If attributes user and password are set, these credentials are used for basic authentication.
Otherwise the current credentials of the calling client are used. To set the basic authentication credentials on client side, the Natural logon must be enabled. User-specific credentials can be overwritten by setting RPC user ID and RPC password in the client application.
false Deactivate basic authentication. All other parameters in this table are ignored.
user O Name of default user for basic authentication.
password O Password of default user for basic authentication.
password-encryption O Specifies how the password is encrypted. Possible values:
plainText Default.
base64  
encrypt The XML/SOAP RPC Server encrypts the password and sets this value.
httpConnectionTimeout R HTTP connection timeout in seconds.

See Reference - HTTP and Java Interface for explanation of attributes.

The section <xmms> contains the optional attributes for SOAP mapping.

Attribute Description
soapVersion Specifies a SOAP version: 1.1 (default) or SOAP 1.2.
wsdl The location of WSDL file, using a WSDL file the target address is retrieved from WSDL file.
service The service name in WSDL file.
port The port name in WSDL file.
repository The repository directory used for WS-* features. See Software AG Web Services Stack client repository.
usernameToken Valid values: PasswordText | PasswordDigest.

Prerequisites: Attribute repository must be defined and module rampart must be engaged. See also UsernameToken Security.

Sample configuration file:

<?xml version="1.0" encoding="UTF-8" ?> 
<EntireX 
  xmlns="http://namespaces.softwareag.com/entirex/xml/runtime/configuration" 
  version="9.12">
  <XmlRuntime Version="1">

   <TargetServer name="http://localhost:1973/MyService">
      <xmms>
        <exx-xmm name="c:\mydir\xmmfiles\XmmExample.xmm" 
          soapVersion="1.1" 
          wsdl="c:/mywsdl.wsdl" service="myservice" 
          port="myserviceSOAP11Port" repository="c:\myrepository"\>
      </xmms>
    </TargetServer>
  </XmlRuntime>
<EntireX>

HTTP Basic Authentication

Basic authentication is used for a target server if the attribute basicAuthentication is defined in the TargetServer block. Basic authentication is used for all calls associated with the defined XMM files for the <TargetServer>.

Basic authentication can be used with fixed credentials or credentials set from the RPC client application:

  • If <TargetServer> contains attributes user and password, these settings are used for basic authentication.

  • Otherwise the RPC client application must provide the credentials: Enable Natural logon and set RPC user ID and RPC password.

See also Generating a Web Service with HTTP Basic Authentication and UsernameToken Authentication for EntireX Authentication under Using the EntireX Web Services Wrapper.

UsernameToken Security

UsernameToken security is used for a target server if attribute usernameToken is defined in <xmms>. Two kinds of UsernameToken are supported:

  • PasswordText

  • PasswordDigest

The repository must be defined in section <xmms>, for example: 

<exx-xmm name="AService.xmm" soapVersion="1.1" 
repository="myrepository" usernameToken="PasswordText" />

The repository must contain module rampart. In the configuration file (axis2.xml) the rampart module must be engaged (<module ref="rampart"/>) and the phase PreSecurity can be empty (<phase name="PreSecurity" />).

Natural logon must be set in the RPC client application. Additionally the RPC client application should set RPC user ID and RPC password.

See also Generating a Web Service with HTTP Basic Authentication and UsernameToken Authentication for EntireX Authentication under Using the EntireX Web Services Wrapper.

WS-Policy

For specifying features such as WS-Policy, see configuration of Software AG Web Services Stack.

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.

To use SSL with XML/SOAP RPC Server, you need to configure two sides: the RPC server side and the target server side.

Start of instruction setTo configure SSL/TLS with the RPC server side

  1. 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.

  2. Set up the XML/SOAP 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.

  3. Make sure the SSL server to which the XML/SOAP 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

Using HTTPS to the target server requires setting Java SSL/TLS properties and changing the protocol of the target server's Web service in the Configuration File.

Start of instruction setTo configure SSL/TLS to a target server

  1. Set the following Java SSL/TLS properties.

    Parameter Description
    -Djavax.net.ssl.keyStore=filename_without_blanks Here we keep the certificate and the private signing key of our client application, which is the RPC server.
    -Djavax.net.ssl.keyStorePassword=myPassword The password that protects the keystore.
    -Djavax.net.ssl.keyStoreType=pkcs12 If not jks (default).
    -Djavax.net.ssl.trustStore=filename_without_blanks Here we keep the trusted certificate of the Web service host or the certificate of its signing (issuing) certificate authority.
    -Djavax.net.ssl.trustStorePassword=myPassword The password that protects the truststore.
    -Djavax.net.ssl.trustStoreType= If not jks (default).

    The properties can be set for example in the Start Script. Example: 

    set CLASSPATH=.;.\classes\entirex.jar;..\WS-Stack\lib\wsstack-client.jar

set PROXYSETTINGS=-Dhttps.proxySet=true
-Dhttps.proxyHost=sslproxy.mydomain 
-Dhttps.proxyPort=443 
-Dhttps.nonProxyHosts="localhost" 

set SSL=-Djavax.net.ssl.keyStore=C:\myKeystore.p12 
-Djavax.net.ssl.keyStorePassword=myKeystorePassword
-Djavax.net.ssl.keyStoreType=pkcs12 
-Djavax.net.ssl.trustStore=C:\myTrustStore.jks 
-Djavax.net.ssl.trustStorePassword=myTruststorePassword

java -classpath %CLASSPATH% %SSL% %PROXYSETTING% com.softwareag.entirex.xml.rt.XMLRPCServer

    For more information about Java and SSL, see your Java documentation (JSSE documentation).

  2. Optional. If you are using an HTTPS target server's Web service address located outside the firewall, set the following Java properties:

    • https.proxyHost

    • https.proxyPort

    • http.nonProxyHosts

    • https.proxyUser

    • https.proxyPassword

  3. Change the protocol of the target server's Web service address from http to https in the configuration file. Specify the fully qualified host name as TargetServer. The host name has to match the CN (Common Name) item of the host certificate. See also Configuration File. Example: 

    <?xml version="1.0" encoding="iso-8859-1" ?>
<EntireX
xmlns="http://namespaces.softwareag.com/entirex/xml/runtime/configuration" version="9.12"
>
    <XmlRuntime Version="1">
       <TargetServer name="https://targethost:8080/entirex/xmlrt">
            <xmms>
                <exx-xmm name="yourFile1.xmm" />
                <exx-xmm name="yourFile2.xmm" />
            </xmms>
        </TargetServer>
    </XmlRuntime>
</EntireX>

Starting the RPC Server

Start of instruction setTo start the XML/SOAP RPC Server

  • Use the Start Script.

    Or:
    At the command prompt, enter: 

    java com.softwareag.entirex.aci.XMLRPCServer broker_id server_address

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

Stopping the RPC Server

Start of instruction setTo stop the XML/SOAP RPC Server

Running the RPC Server as a Windows Service

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

Start of instruction setTo run the XML/SOAP RPC Server as a Windows Service

  1. Customize the Start Script according to your system installation.

    Note:
    The script file must pass external parameters to the RPC server: 

    java com.softwareag.entirex.xml.rt.XMLRPCServer %*

    See also Starting the RPC Server.

  2. Test your RPC server to see whether it will start if you run your script file.

  3. Use the EntireX RPC Service Tool and install the RPCService with some meaningful extension, for example MyServer. If your Start Script is jxmlrpcserver.bat, the command will be 

    RPCService -install -ext MyServer -script install_path\EntireX\bin\jxmlrpcserver.bat

    The log file will be called RPCservice_MyServer.log.

  4. 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".