The EntireX XML/SOAP Listener runs in a servlet-enabled Web server with an installation of the Software AG Web Services Stack. It plugs the Web service's archives (EntireX Workbench file with extension .aar) into Web servers. Typically the Web service clients access the XML/SOAP Listener and send/receive XML/SOAP documents using HTTP/HTTPS. This component was formerly referred to as "XML Servlet".
This document covers the following topics:
See also Web Services Stack documentation in the Software AG Infrastructure Administrator's Guide, also available under http://documentation.softwareag.com > Guides for Tools Shared by Software AG Products.
Individual settings for Web services or groups of Web services are contained in the services.xml file that is part of a Web service archive (Workbench file with extension .aar). Those settings originate from the Web Services Wrapper (default settings from generation) or from the Web Services Stack Configuration Editor (customized settings).
With an external configuration file you can override settings of the Web service's archive (EntireX Workbench file with extension .aar) without modifying the Web service archive itself. This means you can use the same Web service archive in different Web server 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="%USERPROFILE%/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-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. |
This section covers the following topics:
If you want to deploy Web Services Stack Web application and EntireX XML runtime to your own Apache Tomcat installation, perform the following steps:
To deploy to your own Apache Tomcat installation
Stop Apache Tomcat.
Make sure that the attribute unpackWars is set to "true" in the
server.xml of your Apache Tomcat installation.
Copy wsstack.war to the webapps directory of your Apache Tomcat installation.
Start Apache Tomcat. The content of wsstack.war will be expanded into a directory wsstack under the webapps directory of the Apache Tomcat installation.
Stop Apache Tomcat.
Copy entirex.jar from the classes directory of your EntireX installation to the WEB-INF/lib directory of the expanded Web Services Stack Web application.
Start Apache Tomcat.
Now you can deploy generated EntireX Web services (.aar) from the EntireX Workbench.
If you want to deploy the Web Services Stack Web application to WebSphere 8.5.x, perform the following steps:
To deploy to WebSphere 8.5.x
Copy Software AG_directory/WS-Stack/webapp/wsstack.war to a temporary location.
Unpack the WAR file.
Copy all MAR files from WEB-INF/modules to WEB-INF/lib and change their extensions to JAR.
Important:
There might be an issue with mapping of MAR files when using Microsoft Office.
When you have Microsoft Office installed, you cannot rename those files using Windows Explorer.
In this case, use the ren command prompt command.
For example, <TEMP_Directory>\WEB-INF\modules>copy addressing-1.41.mar addressing-1.41.jar copies the MAR file and changes its extension from MAR to JAR.
Copy entirex.jar to folder../wsstack/WEB-INF/lib.
Recreate the WAR file. You can use WinZip or any other application with support for ZIP files.
Log on to the Administrative Console and navigate to Applications > New Application > New Enterprise Application.
Enter the location of the wsstack.war file or browse for it using the button. Then click .
Select the Fast Path - Prompt only when additional information is required radio button and then click .
Click and leave the default values for the options in the Step 1 Select installation options, Step 2 Map modules for servers, and Step 3 Map virtual hosts for Web modules screens.
Click to go to the Step 4 Map context roots for Web modules screen, and type in "wsstack" in the Context root field.
Click to save the changes to the master configuration.
Navigate to Applications > Application Types > WebSphere Enterprise Applications.
Click wsstack_war to open the configuration dialog.
In the configuration dialog, click the Class loading and update detection link.
For Class loader order, select Classes loaded with local class loader first (parent last) radio button.
For WAR class loader policy, select Single class loader for application radio button.
Navigate to Applications > Application Types > WebSphere Enterprise Applications.
Start the Web Services Stack Web application.
To deploy wsstack.war as Web application for WL server
Explode wsstack.war in a directory named wsstack.
Add a file named weblogic.xml to the folder ../wsstack/WEB-INF. weblogic.xml has the following content:
<weblogic-web-app>
<container-descriptor>
<prefer-web-inf-classes>true</prefer-web-inf-classes>
</container-descriptor>
</weblogic-web-app>Copy entirex.jar to folder../wsstack/WEB-INF/lib.
Open the weblogic console (e.g. http://localhost:7001/console.
Select Deployments.
Choose .
Select wsstack(open directory) as current location and choose .
Select Install this deployment as an application and choose .
Select DD only for security and I will make the deployment accessible from the following location for Source accessibility.
Enter the path to the wsstack folder and choose .
Choose Finish.
To deploy example.aar in wsstack Web application
As a prerequisite, Basic Authentication for your WL server has to be disabled.
There are two ways to do this:
Edit config.xml of your WL server and add <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>
under <security-configuration>.
Use the WebLogic scripting tool to modify the enforce-valid-basic-auth-credentials attribute.
connect('weblogic','weblogic','t3://localhost:7001')
edit()
startEdit()
ls()
cd('SecurityConfiguration')
ls()
cd('base_domain')
ls()
set('EnforceValidBasicAuthCredentials','false')
ls()
save()
activate()
print 'Now Restart Your Server...'
The XML/SOAP Listener supports both conversion and translation. See Internationalization with EntireX for more information.