Version 9.5 SP1
 —  Administration under UNIX  —

Administering the EntireX XML/SOAP RPC Server

With the XML/SOAP RPC Server you can process XML-based server calls from EntireX RPC clients/Natural RPC clients. The EntireX RPC client communicates with the XML-based server, using the XML/SOAP RPC Server.


Administering the EntireX XML/SOAP RPC Server

The XML/SOAP RPC Server uses the following, in the following order of priority:

  1. Command-line Parameters
    The command-line parameters have the highest priority.

  2. Properties File
    The properties file is located in the working directory by default. It should define parser settings and the location of the configuration file. The default name of the properties file is entirex.xmlrpcserver.properties. Furthermore it may contain several properties for the server (see the table below).

  3. Configuration File
    The configuration file (XML format) has the lowest priority. It contains a list of target servers, including the mapping file associated with them and may contain information about the broker if not already given in the command-line or property file.

    If the properties file does not specify the location and name of the configuration file, the configuration file in the working directory is used.

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 connection to a host.

Note:
Requires http.keepAlive=true

Integer > 0 5

Top of page

Command-line Parameters

Name Command-line Option Default Value 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 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.logfile -logfile   Path and name of the trace output file. 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.monitorport -smhport 0 The port where the server listens for commands from the System Management Hub (SMH). If this port is 0, no port is used and the management by the SMH is disabled.
entirex.server.name     The name of the server.
entirex.server.password -password   The password for secured access to the Broker. For Java 1.4 and above, 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. For Java 1.3 and below, password encryption is not available.
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 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).
entirex.sdk.xml.runtime.
xmlparserfactory
-jaxp.saxparserfactory com.ctc.wstx.stax.
WstxInputFactory
Location and name of stream parser factory class.
entirex.sdk.xml.runtime.
useCharacterReference
  no Enables or disables the usage of character references. Defined value = yes,no.
entirex.sdk.xml.runtime.
defaultFaultDocumentFormat
  soap Define the protocol used for fault document generation if no fault document is defined. Defined values = soap, xml.

Top of page

Sample Properties File

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

Top of page

Configuration File for the XML/SOAP RPC Server

Introduction

The configuration file for the EntireX XML/SOAP RPC Server 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="7.2.1" >
      <XmlRuntime Version="1">
      <!-- information for XML/SOAP RPC Server-->
      </XmlRuntime>
</EntireX>

The default name of the configuration file is entirex.xmlrpcserver.configuration.xml.

The XMLRPCServer information contains two information blocks, one for the EntireX Broker information and one for a list of target servers.

Sample Configuration File

<?xml version="1.0" encoding="UTF-8" ?> 
<EntireX 
  xmlns="http://namespaces.softwareag.com/entirex/xml/runtime/configuration" 
  version="8.0">
  <XmlRuntime Version="1">
    <BrokerInfo>
      <BrokerId>localhost:1971/</BrokerId>
      <ServerAddress>RPC/SRV1/CALLNAT</ServerAddress>
      <Logical_BrokerId></Logical_BrokerId>
      <Logical_Service></Logical_Service>
      <Logical_SetName></Logical_SetName>
      <Options/>
     </BrokerInfo>

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

TargetServer Block

The section <TargetServer>

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

The section <xmm> 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 Common Web Services Stack client repository.
usernameToken Valid values: PasswordText | PasswordDigest.

Prerequisites: Attribute repository must be defined and module rampart must be engaged. See also XML/SOAP RPC Server with UsernameToken.

The list of target servers (based on the target server entries starting with tag TargetServer and have a mandatory HTTP address) is assigned to the attribute name. Each TargetServer entry can have a list of XMMs for this server.

Caution:
It is not allowed to use one XMM in more than one TargetServer entry inside one configuration file. Using different XMMs with a common definition results in unexpected behavior of XML/SOAP RPC Server.

Top of page

Configuring the XML/SOAP RPC Server

Start of instruction setTo configure the XML/SOAP RPC Server

  1. Specify the file entirex.xmlrpcserver.properties in the directory where the XML/SOAP RPC Server is started.

  2. Specify the JAXP parameters. This step is optional if these parameters are already specified in your environment.

  3. Specify the location of the configuration file.

  4. Specify the configuration file: entirex.xmlrpcserver.configuration.xml.

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

Tip:
If you are using the XML/SOAP RPC Server with an HTTP server located outside the firewall, set the following Java properties:

Top of page

XML/SOAP RPC Server with HTTP Basic Authentication

The XML/SOAP RPC Server uses basic authentication for a Web service if the configuration contains the attribute basicAuthentication block in <TargetServer>. Basic authentication is used for all calls associated with defined XMM files for the <TargetServer>.

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

See Configuration File for the XML/SOAP RPC Server.

Top of page

XML/SOAP RPC Server with UsernameToken

The XML/SOAP RPC Server uses UsernameToken security for a Web service if the configuration contains the attribute usernameToken in <xmm>. The XML/SOAP RPC Server supports two kinds of UsernameToken:

The XML/SOAP RPC Server configuration must define the repository, 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" />).

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

See Configuration File for the XML/SOAP RPC Server.

Top of page

Using SSL or TLS with the XML/SOAP RPC Server

Using HTTPS with XML/SOAP RPC Server requires setting Java properties and changing the protocol from http to https in the configuration file. This section covers the following topics:

See also Configuration File for the XML/SOAP RPC Server.

SSL or TLS Settings

Start of instruction setTo configure SSL communication for the JRE

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

Sample Start Script

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 the changes that are required to the start script, see your Java documentation (JSSE documentation).

Configuration File Settings

Specify the fully qualified host name as TargetServer. The host name has to match the CN (Common Name) item of the host certificate.

<?xml version="1.0" encoding="iso-8859-1" ?>
<EntireX
xmlns="http://namespaces.softwareag.com/entirex/xml/runtime/configuration" version="8.0"
>
    <XmlRuntime Version="1">
       <BrokerInfo>
       <BrokerId>localhost:1971</BrokerId>
       <ServerAddress>RPC/XMLSRV1/JAVA</ServerAddress>
       </BrokerInfo>
       <TargetServer name="https://targethost:8080/entirex/xmlrt">
            <xmms>
                <exx-xmm name="yourFile1.xmm" />
                <exx-xmm name="yourFile2.xmm" />
            </xmms>
        </TargetServer>
    </XmlRuntime>
</EntireX>

Top of page

Java API for XML/SOAP RPC Server

The Java API for XML/SOAP RPC Server is a functional extension to the XML/SOAP RPC Server. It allows you to direct the calls to a Java object instead of a Web service (via HTTP(s)). The usage of Java API for XML/SOAP RPC Server is similar to what is known for the XML/SOAP RPC Server. It only differs in the start script and a new (additional) keyword in the configuration file. See Configuring the XML/SOAP RPC Server above.

Properties File

The property file is the same as the Sample Properties File for the XML/SOAP RPC Server.

Configuration File

The Java API for XML/SOAP RPC Server also uses the same configuration file as the XML/SOAP RPC Server.

The services (programs) directed to the Java interface of the XML/SOAP RPC Server have to use a special keyword "xmlrpcServerClass" as the value of the attribute "Targetserver". A mixture of targetserver with Java and http-interface is also possible.

Example:

<?xml version="1.0" encoding="UTF-8" ?>
<EntireX
xmlns="http://namespaces.softwareag.com/entirex/xml/runtime/configuration"
version="8.3"
>
<XmlRuntime Version="1">
<BrokerInfo>
<BrokerId>localhost:1971</BrokerId>
<ServerAddress>RPC/SRV1/CALLNAT</ServerAddress>
</BrokerInfo>
<TargetServer name="xmlrpcServerClass">
<xmms>
<exx-xmm name="java-service1.xmm" />
<exx-xmm name="java-service2.xmm" />
<exx-xmm name="java-service3.xmm" />
</xmms>
</TargetServer>
<TargetServer name="http://myWebService">
<xmms>
<exx-xmm name="http-service1.xmm" />
<exx-xmm name="http-service2.xmm" />
</xmms>
</TargetServer>
</XmlRuntime>
</EntireX>

Implementation of the Java API for XML/SOAP RPC Server

The Java API for XML/SOAP RPC Server requires a user-written Java class initializing the XML/SOAP RPC Server and implementing the XMLRPCServerInterface.

Example:

import java.util.Properties;
import com.softwareag.entirex.xml.rt.XMLRPCServerInterface;
import com.softwareag.entirex.xml.rt.XMLRPCServer;
public class MyXMLRPCServer implements XMLRPCServerInterface
{
  public MyXMLRPCServer ()
  {
    XMLRPCServer xmlRpcServer = new XMLRPCServer();
    // register your implementation of XMLRPCServerInterface
    xmlRpcServer. registerXMLRPCServerClass ((XMLRPCServerInterface) this);
    // start XML/SOAP RPC Server with arguments (same as command line)
    xmlRpcServer.start(new String[0]);
  }

  // mandatory method invoke (from XMLRPCServerInterface)
  // - thread synchronization must be done by application if required
  // - properties object contains property "charset" (as used in xml-declaration)
  // and property "java.charset" - the corresponding Java codepage
  // - Exception thrown from this method is mapped to error class 2000 and error number 200,
  //   with exception information in errortext

  public byte[] invoke(byte[] requestDocument, Properties properties)
    throws Exception
  {
    byte[] response = null;
    // TODO <insert application code here>
    return response;
  }

  public static void main(String[] args)
  {
    MyXMLRPCServer myServer = new MyXMLRPCServer ();
  }
}

Start Script

The XML/SOAP RPC Server with Java interface must be started by implementing XMLRPCServerInterface as in this example:

java  -classpath "%PARSER%;%CLASSPATH%" MyXMLRPCServer

Top of page

Starting the XML/SOAP RPC Server

Start of instruction setTo start the XML/SOAP RPC Server

If the Java interpreter is not called "java", change the call to "java".

Top of page

Stopping the XML/SOAP RPC Server

Start of instruction setTo stop the XML/SOAP RPC Server

Top of page

Running the XML/SOAP RPC Server in the Software AG Runtime

This section covers the following topics:

See also XML/SOAP RPC Server in the Software AG Runtime under Frequently Asked Questions (FAQ) and Troubleshooting in the XML/SOAP Wrapper documentation.

Introduction

The Software AG Common Platform is a Java runtime environment based on the OSGi framework. It provides a standard platform on which to run Software AG products and the enterprise applications you develop around those products. The Software AG Common Platform provides common infrastructure for user authentication, event handling, and the execution of Web applications. Infrastructure components that the Software AG Common Platform provide include Software AG Security Infrastructure, Software AG Web Server based on Apache Tomcat, and Web Services Stack.

The Software AG Runtime is an installable instance of the Software AG Common Platform that functions as a stand-alone Tomcat server and a container for Web applications. EntireX uses the Software AG Runtime to host the EntireX XML/SOAP Listener and XML/SOAP RPC Server.

The Software AG Web Server based on Apache Tomcat is one of the basic infrastructure components provided by the Software AG Common Platform. It provides HTTP/HTTPS services, a JSP engine, and a servlet container. Unlike a typical Tomcat implementation, the Software AG Web Server is OSGi-based and supports both .WAR-based and .WAB-based web applications.

During startup, the Software AG Web Server (service name: Software AG Runtime), including the EntireX bundle, looks in the EntireX profile for file <Installation home>/EntireX/etc/EXX/workspace/entirex.servers.properties. This file defines an XML/SOAP RPC Server as within entirex.xmlrpcserver.properties and entirex.xmlrpcserver.configuration.xml located in the EntireX installation in subdirectory config by default.

Configuration

The file entirex.servers.properties defines the servers to be started. It is only read during startup of the Software AG Runtime. Set the following properties for each defined server:

Property Name Description
server.<n>.kind Must be "XMLRPCServer".
server.<n>.propertiesFile Path to properties file (Java notation).
server.<n>.configurationFile Path to configuration file (Java notation).

where <n> is a number identifying the server

Example of entirex.servers.properties:

server.1.kind=XMLRPCServer
server.1.propertiesFile=c:/SoftwareAG/EntireX/config/entirex.xmlrpcserver.properties
server.1.configurationFile=c:/SoftwareAG/EntireX/config/entirex.xmlrpcserver.configuration.xml
server.2.kind=XMLRPCServer
server.2.propertiesFile=c:/SoftwareAG/EntireX/config/entirex.myxmlrpcserver.properties
server.2.configurationFile=c:/SoftwareAG/EntireX/config/entirex.myxmlrpcserver.configuration.xml

Deactivating an XML/SOAP RPC Server Permanently

To stop any XML/SOAP RPC Server permanently (including the default XML/SOAP RPC Server), rename the configuration file entirex.servers.properties under EntireX\etc\exx\workspace, for example to entirex.servers.properties.bak.

Starting and Stopping the XML/SOAP RPC Server using JMX (Java Management Extensions)

To start and stop an XML/SOAP RPC Server, open a JMX tool, for example the Java Monitoring and Management Console (jconsole), located in the Java bin directory (sample path: C:\SoftwareAG\jvm\w64_160\bin\jconsole.exe). The tool should be connected to the Software AG Runtime JMX port remotely. The default number of this port is 8044 and is defined in <Installation home>/ profiles/CTP/configuration/config.ini.

Switch to tab MBeans and select item com.softwareag.entirex.runtime.rpcserver. The following operations are available:

Operation Description
startServer To start a registered and non-running XML/SOAP RPC Server. The parameter is the service name (e.g. RPC/XMLSERVER/CALLNAT).
stopServer To stop a running XML/SOAP RPC Server. The parameter is the service name (e.g. RPC/XMLSERVER/CALLNAT).
registeredServer Returns the list of service names of all configured XML/SOAP RPC Servers.
runningServer Returns the list of service names of running configured XML/SOAP RPC Servers.
nonRunningServer Returns the list of service names of non-running configured XML/SOAP RPC Servers.

Starting and Stopping the XML/SOAP RPC Server under UNIX

Under UNIX, the Software AG Runtime can be stopped and started, using the following scripts:

<SuiteInstallDir>/profiles/CTP/bin/sagctp<nn>.sh stop
<SuiteInstallDir>/profiles/CTP/bin/sagctp<nn>.sh start

where <nn> represents the product version number.

Top of page