The EntireX XML/SOAP Listener is part of the EntireX XML/SOAP Runtime. It plugs the generated AAR file, including XMM files, into Web servers and so enables the EntireX XML/SOAP Runtime to send and receive XML documents using HTTP/HTTPS to/from a Web server. This component was formerly referred to as "XML Servlet".
This document covers the following topics:
The EntireX XML/SOAP Listener requires a servlet-enabled Web server with an installation of Software AG Common Web Services Stack (WSS). See the separate Web Services Stack documentation. Client programs can access the XML/SOAP Runtime through HTTP/HTTPs interfaces provided in programming environments.
The initialization parameters are set using the packaging wizard.
| Name in Web Services Wrapper | Parameter | Description |
|---|---|---|
| Default wait time | exx-default-waittime | Sets the value of the default wait time field to
the argument (see setDefaultWaittime of class BrokerService).
|
| Servlet internal sweep time | exx-sweeptime | Interval in which the servlet checks and frees unused resources. The default is 60 seconds. |
| Enable character reference | exx-use-characterreference | Enable/disable the character reference for the XML payload. |
| Behavior of non-conversation calls | exx-mep | The parameter indicates whether a
non-conversational call is finalized with a logoff call to free Broker resource
(default), or by means of timeout.
The default value for this parameter is
"nonConv-with-logoff", which defines that a
non-conversational call will finish with an additional logoff call (two calls
per message). Set |
The EntireX init file is generated by the packaging wizard that is called from the context menu of Software AG IDL or XMM files. It contains the XML/SOAP Listener initialization parameters.
With an external configuration file you can redefine settings of some of the parameters for an EntireX Web service archive without modifying the EntireX Web service archive itself. This means you can use the same EntireX web service archive in different environments.
To use an external configuration file
Define a name and a location for the external configuration file.
In the parameter section of file axis2.xml,
define a parameter "EntireX-XML-Listener" within a parameter "services".
For the attribute "location" in parameter
"services",
specify an absolute or relative path to the external configuration file.
File axis2.xml can be found in the conf
directory or folder of the Web Services Stack Web application.
<parameter name="EntireX-XML-Listener">
<parameter name="services" location="<path for file
overwriting settings of EntireX services>" />
</parameter>
Notes:
location="$EXXDIR/config/myconfig.xml".
Define services in the external configuration file.
External configuration files are XML documents with a root element "serviceGroup". A service group is defined as a sequence of one or more services.
To identify the service you are defining, specify an identifier for the attribute "name", for instance <service name= "service100">.
To make common settings, that is, settings for all services, use an asterisk as identifier (<service name= "*">. Note that an individual setting can override a common setting.
EntireX web service parameters that can be set are defined as subelements of "service". See the table below.
| Parameter | Description |
|---|---|
<exx-brokerID> |
The broker ID to use. |
<exx-service> |
The service name is the triple set of server class/server name/service. |
<exx-userID> |
The user ID specified here is used for calling the broker. |
<exx-password> |
The user ID specified here is used for calling the broker. |
<exx-password-encryption> |
Specifies how the password is encrypted in the configuration file. Encryption is performed automatically when the configuration file is read for the first time. |
<exx-use-security> |
Possible values: true|false. |
<exx-encryption-level> |
Possible values: 0|1|2. |
<exx-rpc-userID> |
The RPC user ID specified here is used for Natural Security |
<exx-rpc-password> |
The RPC Password specified here is used for Natural Security. |
<exx-natural-security> |
Enable/Disable the Natural Security (true|false). |
<exx-natural-library> |
The Natural library to use. |
<?xml version="1.0" encoding="utf-8" ?>
<serviceGroup>
<!-- Optional section for all EntireX services -->
<service name="*">
<exx-brokerID>host:1234</exx-brokerID>
<exx-service>RPC/SRV1/CALLNAT</exx-service>
</service>
<!-- service100 overwrites the service address -->
<service name="service100">
<exx-service>RPC/SRV2/CALLNAT</exx-service>
</service>
<!-- service101 adds library setting -->
<service name="service101">
<exx-natural-library>MYLIB</exx-natural-library>
</service>
</serviceGroup>
The XML/SOAP Listener allows you to use the user credentials from the incoming request by means of Basic Authentication or
UsernameToken.
The same credentials are used for EntireX Broker authentication and (Natural) RPC Server authentication.
This means you need to make some settings for the EntireX Web service in Web Service Wizard and Configuration Editor.
Note:UsernameToken is part of WS-Security. See WS-Security UsernameToken Specification.
See also Example: Setting up an EntireX Client to Consume a Secured Web Service in the IDL Extractor for WSDL documentation.
The priority of credentials settings is as follows:
exx-userID, exx-password, exx-rpc-userID, exx-rpc-password (highest priority)
UsernameToken
Basic Authentication (lowest priority)
To use the XML/SOAP Listener with Basic Authentication and UsernameToken Authentication
Select an IDL file or XMM file.
Choose .
Disable check box Use Defaults.
Enable at least General service parameters....
If using EntireX Security or Natural Security, enable Set connection and security... too.
Press .
Enable the required authentication. In this example, both possibilities of web service authentication are enabled.
Press .
The page with XMM settings appears if it was selected before (step 5). Enable the required security (EntireX Security and/or Natural Logon).
Press and follow the wizard.
After generating the web service archive (extension "aar"), open the generated AAR file with the Configuration Editor (e.g. with double click).
For more information on the Configuration Editor see Configuring Web Services.
The XML/SOAP Listener supports both conversion and translation. See Internationalization with EntireX for more information.
Example of ETB_TRANSPORT:
| Shell | set the environment variable: | delete the environment variable: |
|---|---|---|
| C Shell | setenv ETB_TRANSPORT value |
unsetenv ETB_TRANSPORT |
| Bourne or Korn Shell | ETB_TRANSPORT=value |
unset ETB_TRANSPORT |