The EntireX RPC Server for XML/SOAP allows RPC clients to communicate with target servers via HTTP(S). The RPC Server for XML/SOAP transforms RPC client calls into XML/SOAP calls. It works together with the XML/SOAP Wrapper.
This document describes how to administer the RPC Server for XML/SOAP with local scripts as in earlier versions of EntireX. It covers the following topics:
See also Administering the RPC Server for XML/SOAP with the Command Central GUI | Command Line.
The following elements are used to set up the RPC Server for XML/SOAP:
The start script for the RPC Server for XML/SOAP 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, wsstack-client.jar and saglic.jar.
The RPC Server for XML/SOAP accepts two unnamed parameters, broker_id
and server_address
.
Default values are localhost:1971
and RPC/SRV/CALLNAT
. Example:
java –Dentirex.license.location=<license.xml with path> com.softwareag.entirex.xml.rt.XMLRPCServerbroker_id
server_address
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.
Additionally, Java system properties are available to administer the RPC Server for XML/SOAP. 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: |
Integer > 0 | 5 |
http.maxTotalConnections |
Define the maximum total number of HTTP connections to a host.
If Note: |
Integer > 0 | 20 |
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="10.5.0" >
<XmlRuntime Version="1">
<!-- information for RPC Server for XML/SOAP, see TargetServer
Block -->
</XmlRuntime>
</EntireX>
The RPC Server for XML/SOAP 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 | Explanation | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
entirex.server.brokerid |
-broker |
Broker ID. Default: localhost .
|
||||||||||||||||||||
entirex.server.codepage |
-codepage |
The encoding configured for the Java virtual machine (JVM) is used to convert the Unicode (UTF-16) representation within Java to the encoding sent to or received from the broker by default. This encoding is also transferred as the codepage to the broker to tell the broker the encoding of the data. Changing the default encoding of the JVM has the side effect that the encoding for terminal and file IO is affected too. This may be undesired. With the codepage parameter you can override the encoding without the need to change the default encoding of the JVM. The codepage must be supported by your JVM. For a list of valid encodings, see Supported Encodings in your Java documentation. Note: Enable character conversion in the broker by setting the service-specific attribute |
||||||||||||||||||||
entirex.server.compresslevel |
-compresslevel |
|
||||||||||||||||||||
entirex.server.development.relativepaths |
The file locations of deployed XMM and WSDL files are written as relative paths in configuration file of the RPC Server for
XML/SOAP. Default: false .
|
|||||||||||||||||||||
entirex.server.fixedservers |
no |
|
||||||||||||||||||||
entirex.server.ignoreSOAPActionNamespace |
true : Only the name part of SOAPAction is used, the namespace is ignored.false : The SOAPAction value is used as defined. Default: false .
Note: |
|||||||||||||||||||||
-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 |
Maximum number of worker threads. Default: 32 .
|
|||||||||||||||||||||
entirex.server.minservers |
Minimum number of server threads. Default: 1 .
|
|||||||||||||||||||||
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. To disable password
encryption, set entirex.server.passwordencrypt=no .Default: yes .
|
||||||||||||||||||||
entirex.sdk.xml.runtime.propertyfile |
-propertyfile |
The file name of the property file. Default: entirex.xmlrpcserver.properties .
|
||||||||||||||||||||
entirex.sdk.xml.runtime.configurationfile |
-configurationfile |
Location and name of configuration file. Default: entirex.xmlrpcserver.configuration.xml .
|
||||||||||||||||||||
entirex.server.restartcycles |
-restartcycles |
Number of restart attempts if the Broker is not available. This
can be used to keep the RPC Server for XML/SOAP running while the Broker is
down for a short time. Default: 15 .
|
||||||||||||||||||||
entirex.server.security |
-security |
no |yes |auto |name of BrokerSecurity object. Default: no .
|
||||||||||||||||||||
entirex.server.serveraddress |
-server |
Server address. Default: RPC/SRV1/CALLNAT .
|
||||||||||||||||||||
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 |
The user ID for access to the broker. | ||||||||||||||||||||
entirex.server.waitattach |
Wait timeout for the attach server thread. Default: 600S .
|
|||||||||||||||||||||
entirex.server.waitserver |
Wait timeout for the worker threads. Default: 300S .
|
|||||||||||||||||||||
entirex.timeout |
TCP/IP transport timeout. See Setting the Transport Timeout under Writing Advanced Applications - EntireX Java ACI. Default: 20 .
|
|||||||||||||||||||||
entirex.trace |
-trace |
Trace level. Values: 0|1|2|3 . Default: 0 .
|
||||||||||||||||||||
entirex.sdk.xml.runtime.xmlparserfactory |
-jaxp.saxparserfactory |
Location and name of stream parser factory class. Default: com.ctc.wstx.stax.WstxInputFactory .
|
||||||||||||||||||||
entirex.sdk.xml.runtime. |
soap |
Define the protocol used for fault document generation if no fault document is defined. Values: soap|xml . Default: soap .
|
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.
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.
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:
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 |
|
||||||
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:
|
||||||
httpConnectionTimeout |
R | HTTP connection timeout in seconds. |
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 |
Sample configuration file:
<?xml version="1.0" encoding="UTF-8" ?> <EntireX xmlns="http://namespaces.softwareag.com/entirex/xml/runtime/configuration" version="10.5"> <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>
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:
For how to send the RPC user ID/password pair from an RPC client, see Using the Broker and RPC User ID/Password (.NET Wrapper | Java Wrapper | C Wrapper | PL/I Wrapper | DCOM Wrapper | Web Services Wrapper | IDL Tester | Listener for XML/SOAP | Listener for IBM MQ).
For the COBOL Wrapper, refer to Using Broker Logon and Logoff and Using RPC Authentication (Natural Security, Impersonation, Integration Server).
For non-RPC clients, see Using the Broker and RPC User ID/Password under EntireX XML Tester in the XML/SOAP Wrapper documentation.
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 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.
To use WS-* features such as WS-Policy you need to define the repository location (used by underlying Software AG Web Services Stack) and the WSDL file location, including service name and port name in the configuration file of the RPC Server for XML/SOAP. A sample repository is provided in the installation (<installation_home>/WS-Stack).
For specifying features such as WS-Policy, see configuration of Software AG Web Services Stack.
The following user exit allows you to add HTTP headers before the call, or - in case of HTTP error 401 (authentication) - to add an HTTP header to optional retry call, for example to support SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism).
Implement the interface com.softwareag.entirex.xml.rt.IHttpTransportUserExit
with the two methods
addHttpHeaders
and retryOnAuthenticationError
.
See also the sample implementation, including the Javadoc. Sample user exit:
package sample; import java.util.Properties; import com.softwareag.entirex.xml.rt.IHttpTransportUserExit; /** * implementation of user exit must be thread-safe */ public class SampleHttpTransportUserExit implements IHttpTransportUserExit { private String getToken(String user, String endpoint) { // add your implementation here return ""; } /** * Method to add HTTP header. * Method is called before first call and * if an HTTP error 401 occurred and retryOnAuthenticationError() is true * @param settings properties containing user and endpoint * @param httpHeaders */ @Override public void addHttpHeaders(Properties settings, Properties httpHeaders) { String user = settings.getProperty("user"); String endpoint = settings.getProperty("endpoint"); httpHeaders.setProperty("Authorization", "Negotiate " + getToken(user, endpoint)); } /** * @return should make a retry call on authentication error (401) */ @Override public boolean retryOnAuthenticationError() { return true; } }
On element TargetServer
, add the attribute httpTransportUserExit
with the qualified name of the user exit in the configuration file:
<?xml version="1.0" encoding="UTF-8"?> <EntireX version="10.5" xmlns="http://namespaces.softwareag.com/entirex/xml/runtime/configuration"> <XmlRuntime Version="1"> <TargetServer name="http://localhost:8080/wsstack/services/exampleSOAP" httpConnectionTimeout="60" httpTransportUserExit="sample.SampleHttpTransportUserExit" > <xmms> <exx-xmm name="C:/example.xmm" soapVersion="1.1" /> </xmms> </TargetServer> </XmlRuntime> </EntireX>
Add the user exit to classpath
in the start script.
To set the credentials - this means that the user ID is available in user exit on the client side - the Natural logon must be enabled. User-specific credentials can be overwritten by setting the RPC user ID and RPC password in the client application.
The encoding for the outgoing XML document is determined by the XML Default Encoding defined in the XML mapping file. See Defining the XML Encoding in the XML Mapping Editor documentation.
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 Platform-independent Administration documentation.
To use SSL with RPC Server for XML/SOAP, you need to configure two sides: the RPC server side and the target server side.
To configure SSL/TLS with the RPC server side
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 RPC Server for XML/SOAP 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 RPC Server for XML/SOAP connects is prepared for SSL connections as well. The SSL server can be EntireX Broker or Broker SSL Agent. See:
To configure SSL/TLS to a target server
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.
If the web service has to be called via HTTPS (SSL/TLS), the SSL client (here the RPC Server for XML/SOAP) needs the correct certificate for the web service in the truststore to be able to communicate via SSL. The certificate can either be stored in the default truststore of the JVM or in the truststore specified with the following Java property:
-Djavax.net.ssl.trustStore=path_to_used_truststore
The SSL parameters must be included in quotes, for example
set SSL="-Djavax.net.ssl.trustStore=C:\myTrustStore.jks"
Note:
This is only an example. You must provide a truststore that matches your environment.
The truststore keeps the trusted certificate of the web service host or the certificate of its signing (issuing) certificate
authority.
In the event of an SSL error, you can use the Java property -Djavax.net.debug=all
to get more information.
Add the SSL parameter to the start script of the RPC Server for XML/SOAP and ensure it is passed to the start or Java. Example:
... set SSL="-Djavax.net.ssl.trustStore=C:\myTrustStore.jks -Djavax.net.debug=all" ... "%JAVA_HOME_BIN%java" %PROXY% %SSL% -classpath "%CLASSPATH%" com.softwareag.entirex.xml.rt.XMLRPCServer -p "%EXXPROP%" -c "%EXXCONF%" %*
There are additional Java properties, which are usually not needed. These are described in the Java documentation.
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
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="10.5" > <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>
To start the RPC Server for XML/SOAP
Use the Start Script.
Or:
At the command prompt, enter:
java com.softwareag.entirex.aci.XMLRPCServerbroker_id
server_address
You can pass command-line options and customize your environment as described under Start Script.
To stop the RPC Server for XML/SOAP
Use the command stopService
. See Stop Running 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
To ping the RPC Server for XML/SOAP
Enter the following command:
java -classpath "$EXXDIR/classes/entirex.jar" com.softwareag.entirex.rpcping.RPCServerPing -p <admin_port>
where | admin_port |
is the number of the administration port. |
The ping
command returns "0
" if the server is reachable, and "1
" if the server cannot be accessed.
Note:
This command is particularly useful in a high availability cluster context.
See Setting up your Environment for High Availability with Container Orchestration in the High Availability documentation.
For general information see Running an EntireX RPC Server as a Windows Service.
To run the RPC Server for XML/SOAP 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:
java com.softwareag.entirex.xml.rt.XMLRPCServer %*
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 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.
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".