This document covers the following topics:
See also Generating a Web Service with HTTP Basic Authentication and UsernameToken Authentication for EntireX Authentication under Using the EntireX Web Services Wrapper.
With the Listener for XML/SOAP you can define parameters inside the payload of a message. We recommend this approach rather than HTTP parameters. Define the setting in the SOAP header and under the first tag of XML document as follows:
... <soap-env:Header> <exx:EntireX xmlns:exx="urn:com.softwareag.entirex.xml.rt"> <!-tags with parameter setting e.g: --> <exx-natural-library>libraryname</exx-natural-library> <exx-natural-security>true</exx-natural-security> </exx:EntireX> ... </soap-env:Header> ...
<root-tag> <exx:EntireX xmlns:exx="urn:com.softwareag.entirex.xml.rt"> <!-tags with parameter setting e.g: --> <exx-natural-library>libraryname</exx-natural-library> <exx-natural-security>true</exx-natural-security> </exx:EntireX> ... </root-tag>
It is assumed that you are familiar with the concepts of conversational and non-conversational RPC. See also Conversational RPC.
For conversational RPC you need an instantiated conversation object.
See Conversation
. Conversational RPC is enabled by passing a
reference to this object to the method
setConversation
. See setConversation
. Different stubs can participate in the same
conversation if they use the same instance of a Conversation object. An RPC
conversation is terminated by calling either the
closeConversation
method or the
closeConversationCommit
method for one stub.
To enable conversational RPC
Create a Conversation object and set this with
setConversation
on the wrapper object.
Different wrapper objects can participate in the same conversation if they use the same instance of a conversation object.
To abort a conversational RPC communication
Call the closeConversation
method.
To close and commit a conversational RPC communication
Call the closeConversationCommit
method.
Conversations can only be used in connection with sessions. If the session is interrupted, the conversation will be deleted.
To use conversational RPC
Use the parameter exx-conv
with the value
OPEN.
To continue conversational RPC
Pick up the parameter exx-sessionID
in
response and set the parameter as HTTP parameter or in the same way as in the
response document inside the request document.
To abort a conversational RPC communication
Use the parameter exx-conv
with the value
BACKOUT.
To close and commit a conversational RPC communication
Use the parameter exx-conv
with the value
COMMIT.
See also EntireX XML Tester for Conversational RPC.
Warning: Natural RPC Servers and EntireX RPC Servers behave differently when ending an RPC conversation. |
See also Conversational RPC.
Java-based EntireX applications (including applications using classes generated by the Java Wrapper) may compress the messages sent to and received from the broker. There is a general way to enable compression using broker ID, and another way that depends on whether you use the XML/SOAP Wrapper or the Listener for XML/SOAP.
You may append the keyword compresslevel
with one of the
values below to the Broker ID.
localhost:1971?compresslevel=BEST_COMPRESSION
localhost?poolsize=4&compresslevel=9
Both examples set the compression level to 9.
Set the compression level with the method
setCompressionLevel()
as an integer or a string
argument.
You can use the constants defined in class
java.util.zip.Deflater
.
If the string
starts with Y, compression is switched on with level 6,
starts with N, compression is switched off (level 0).
Permitted values are the integers 0 - 9 and the corresponding strings:
BEST_COMPRESSION |
level 9 |
BEST_SPEED |
level 1 |
DEFAULT_COMPRESSION |
level 6 |
DEFLATED |
level 8 |
NO_COMPRESSION |
level 0 |
To set the compression level
Use the parameter exx-compressLevel
. The
values are described in the section above.
If the target server of your Web service has to be reached through a firewall, set and adjust to your needs the following properties:
-Dhttp.proxySet=true
-Dhttps.proxySet=true
-Dhttp.proxyHost=httpprox.mydomain.org
-Dhttps.proxyHost=sslprox.mydomain.org
-Dhttp.proxyPort=8080
-Dhttps.proxyPort=443
-Dhttp.nonProxyHosts=*mydomain.org|localhost
-Dhttp.proxyUser
-Dhttps.proxyUser
-Dhttp.proxyPassword
-Dhttps.proxyPassword
Add the proxy settings to the start script.
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.
See also Generating a Web Service with HTTP Basic Authentication and UsernameToken Authentication for EntireX Authentication under Using the EntireX Web Services Wrapper.
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 (see Configuration File).
If the web service has to be called via HTTPS (SSL/TLS), the SSL client (here the XML/SOAP Wrapper) 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 XML/SOAP Wrapper 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 (see 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>
This section covers the following topics:
The EntireX XML/SOAP Runtime introduced a feature called null value suppression to reduce to amount of data transferred between Web client and Web service. Null value suppression (NVS) allows you to hide tags or attributes with a specified value (so-called null value).
The different types of NVS are explained below. The EntireX XML Mapping Editor provides two ways of setting/modifying the NVS type:
using a general setting on tab Mapping Parameter
on each element or attribute in the definition of request/response on tab XML Request/ XML Response
For several data types, a null value is defined by default. See Default Definition of Null Value. To change one of these null values, open the XML Request/XML Response tab, select the element/attribute and modify the property of the null value manually. For this modification use the Properties view or the Properties dialog (open with the context menu).
Data Type | Suppression Mode |
---|---|
Simple Elements | No Suppression |
Simple Attributes | No Suppression |
Array Types | Cells at end (trim) |
Complex Types | Suppress group elements |
Tip:
The default setting for elements and attributes changed with version
7.3 from "Suppress Element/Attribute" to
"No Suppression". The null value suppression for
elements and attributes can be set independently. The null value suppression
for Complex Types was introduced with version 7.3.
If there is a significant difference between pure XML and SOAP for a null value suppression mode, two examples are introduced.
Suppression Mode | Valid for |
---|---|
No Suppression | Elements, attributes |
Elements | Elements |
Attributes | Attributes |
Cells at End (Trim) | Elements inside an array definition |
All Empty Cells | Elements inside an array definition |
Suppress Group Elements | Elements inside a group definition |
Depends On Element | Attributes |
The element or attribute is always present in document. The minimum and maximum occurrence of element/attribute must be set to one.
XML Document | Displayed XML Document |
---|---|
<prog> <integer>0</integer> </prog> |
<prog> <integer>0</integer> </prog> |
An element is hidden if
the element value is equal to null value
all attributes of the element can be suppressed
the element has only subelements that can be suppressed
The minimum occurrence of element must be zero, and the maximum occurrence of element must be one.
XML Document | Displayed XML Document |
---|---|
<prog> <gr> <integer>0</integer> </gr> </prog> |
<prog /> |
An attribute with null value is hidden.
The minimum occurrence of attribute must be zero, and the maximum occurrence of attribute must be one.
XML Document | Displayed XML Document |
---|---|
<prog integer="0" name="Henry"/> |
<prog name="Henry"/> |
All elements of array that fulfills the assertion of "Suppress Element/Attribute" are suppressed if its index is higher than the highest index of the non-suppressed element.
The minimum occurrence of elements must be lower than the maximum occurrence, and the maximum occurrence of elements must be the maximum number of elements or unlimited.
XML Document | Displayed XML Document |
---|---|
<prog> <array> <integer>0</integer> <integer>1</integer> <integer>0</integer> <integer>2</integer> <integer>0</integer> <integer>0</integer> </array> </prog> |
<prog> <array> <integer>0</integer> <integer>1</integer> <integer>0</integer> <integer>2</integer> </array> </prog> |
All elements of array that fulfills the assertion of NVS_FIELD are suppressed.
The minimum occurrence of elements must be lower than the maximum of occurrence and maximum occurrence of elements must be maximum number of elements or unlimited.
XML Document | Displayed XML Document |
---|---|
<prog> <array> <integer>0</integer> <integer>1</integer> <integer>0</integer> <integer>2</integer> <integer>0</integer> <integer>0</integer> </array> </prog> |
<prog> <array> <integer>1</integer> <integer>2</integer> </array> </prog> |
SOAP Document | Displayed SOAP Document |
---|---|
<prog> <array> <integer>0</integer> <integer>1</integer> <integer>0</integer> <integer>2</integer> <integer>0</integer> <integer>0</integer> </array> </prog> |
<prog> <array> <integer SOAP-ENC:position="[1]">1</integer> <integer SOAP-ENC:position="[3]">2</integer> </array> </prog> |
The suppression mode allows you to suppress group information if - and only if - all elements of the group can be suppressed.
The minimum occurrence of elements must be zero.
XML Document | Displayed XML Document |
---|---|
<prog> <person> <firstname>Henry</ firstname > <lastname>Miller</ lastname > <someInformation>2</ someInformation > </person> <person> <firstname></ firstname > <lastname></ lastname > <someInformation>0</ someInformation > </person> <person> <firstname>John</ firstname > <lastname>Miles</ lastname > <someInformation>0</ someInformation > </person> </prog> |
<prog> <person> <firstname>Henry</ firstname > <lastname>Miller</ lastname > <someInformation>2</ someInformation > </person> <person/> <person> <firstname>John</ firstname > <lastname>Miles</ lastname > <someInformation>0</ someInformation > </person> </prog> |
Attribute of the element is visible if the element does not have the null value.
The minimum occurrence of attribute and associated element must be zero, and the maximum occurrence must be one.
XML Document | Displayed XML Document |
---|---|
<prog type="integer">0 <parm type="integer">0</parm> </prog> |
<prog /> |
Data Types | Null Value |
---|---|
String | Empty String |
Integer | 0 |
Floating Point | 0.0 |
Numeric | 0.0 |
Time | No default definition |
Date | No default definition |
Binary | No default definition |
Boolean | False |
For further settings, use the method
setUserProperty
in
XMLRPCService
(EntireX XML/SOAP Runtime).
The RPC Server for XML/SOAP maps the values of IDL parameters to XML/SOAP documents and vice versa. If the Web service responds with a fault document, this information is mapped to an error and returned to RPC client normally. With the optional feature Map Fault to IDL Parameter you can map values from a normal response and also from a fault document response. This means that no RPC error is returned to the RPC client; instead the fault information is contained in the IDL file. An RPC error is returned to the client only if internal error processing problems occurred within the RPC Server for XML/SOAP. This feature is available for SOAP and XML documents.
Note:
This example illustrates the feature Map Fault to IDL
Parameter. Other features mentioned here, such as renaming
parameters or assigning a prefix/namespace to a parameter, are described
elsewhere.
/* Sample IDL file library 'Demo' is program 'FaultToIDL' is define data parameter 1 MyRequest In 2 RequestData (AV) 1 MyResponse Out 2 ResponseData (AV) 1 MyStatus Out ** parameters for fault information 2 Code (AV) 2 String (AV) 2 Detail (AV) end-define
To map fault items to IDL
In the XML Mapping Editor, generate a (SOAP) mapping and select the response tab.
Remove the parameter MyStatus
, including
its children, because the regular response will not contain these parameters
and the corresponding IDL parameters will be used for fault information
later.
Open the Fault Document Manager (see bottom of opened tab Response) and select the document to open the following wizard:
In the following steps, map "faultcode", "faultstring" and "detail" to IDL parameters. Fault item "faultactor" is not used in this example.
Select "faultcode" and open the properties shown on the following screen:
Check Fault Mapped to IDL to enable the mapping path button. In this example, a mapping path has not yet been entered and the button is labelled "<none>".
Press the mapping path button.
Select the path to IDL parameter, for example "FaultToIDL/MyStatus/Code" and choose
to display the following screen:Choose
.Repeat the steps above to select the fault items "faultstring" (path to IDL parameter e.g. "FaultToIDL /MyStatus/String") and "detail" (path to IDL parameter e.g. "FaultToIDL /MyStatus/Detail").
Note:
The fault item "info:detail"
contains the complete document fragment enclosed by an associated tag (in this
example tag <detail>).
Choose
to save the IDL-XML mapping.In subsequent steps you need to
Set up the RPC Server for XML/SOAP with this XMM.
Set up a new Web service or use an existing one.
As a quick test, implement a Web service that behaves as follows:
If the "requestData" field contains any data except "throwException", the field "responseData" in the response document is set to a concatenation of the string "Receiving:" and the value of field "requestData". See Request 2).
If the "requestData" field contains "throwException", the Web service responds with a SOAP fault.
The following screen illustrates a request that expects a normal response:
The following response is received (field responseData is filled):
The following screen illustrates a request where a fault document from the Web service is expected:
The following fault information is provided:
xml:space
(see XML specification) on element(s). The attribute xml:space
has the higher priority and is inherited from children of the element recursively.
This section covers the following topics:
The attribute xml:space
can be added in the XML Mapping Editor. Select an element and add new child, select the checkbox for xml:space and choose
. Depending on the application, perform these steps for the request and/or response document definition. The attribute is
added with value "preserve". If another value is required, open the properties on the attribute and change the default value.
Note:
The XML/SOAP Runtime only supports the value "preserve" for attribute xml:space
, all other values disable the preserving of whitespace (that is, whitespace is trimmed).
The steps required to keep whitespace as default depend on the EntireX component:
Listener for XML/SOAP
Add the following line to file axis2.xml in WS-Stack Web application:
<parameter name="exx-xml-space">preserve</parameter>
Java API (XMLRPCService)
Set the user property entirex.sdk.xml.runtime.xmlspace
:
XMLRPCService rpcService = new XMLRPCService(...); ... rpcService.setUserProperty("entirex.sdk.xml.runtime.xmlspace","preserve");
RPC Server for XML/SOAP
Add the following line to properties file of the RPC Server for XML/SOAP:
entirex.sdk.xml.runtime.xmlspace=preserve